Rest API Resources

Overview

Resources in the CoolCalc API are essentially a light wrapper around any piece of application data. In addition to the application data, a resource contains HATEOAS links and status information.

All resources provided by the CoolCalc API include the following attributes:

  • Application data. This may be an individual resource (JSON object) or a collection (JSON array).
  • An array of HATEOAS links. The “links” attribute in any resource contains the HATEOAS links directly related to the given resource.
  • A “navTrail” attribute. The nav trail represents the HATEOAS links related to the resources represented by higher level URL segments.
  • A “status” attribute.

The CoolCalc API provides output in JSON or GeoJSON format. At this time availability of a specific resource in JSON or GeoJSON is controlled by the server, depending on the underlying data. In future revisions the API may add a check for the HTTP "Allow" header in case a client wants plain JSON data even when geo data exists.

One of the principal design characteristics of the CoolCalc applications is that clients should not have to understand the internal details of every resource. The CoolCalc API and client side libraries are designed so clients never have to manipulate resources any more than setting individual attribute values. Put simply, you do not have to construct or format JSON payloads on the client side, only edit individual attribute values based on an earlier resource provided by the server. For the purpose of POST requests (add-to-collection) the API provides a “template” HATEOAS link so clients can download an empty or default resource template, edit the individual attribute values as required and then POST the template (which is now no longer a template) to the collection's “self” link in order to create the new collection item.

Application data

The application data in a JSON resource is a first level attribute where the attribute name represents the resource name and the attribute's value is the corresponding application data. Only one first level attribute dedicated to application data exists in any resource. In GeoJSON resources the application data is contained in the “properties” attribute of any GeoJSON feature.

For individual resources the application data is a JSON object, for collections the application data is a JSON array.

Individual resource: 

"HVACSystem": {
    "HVACSystemId": 123,
    "projectId": 456,
    "HVACSystemName": "A cool system"
    /* ... additional properties here .. */
}

Collection:

"HVACSystems": [
    { /* Collection item */ },
    { /* Collection item */ }
]

Collection items

Collection items are typically an abbreviated representation of the underlying resource. Just like first level resources, collection items are actually a wrapper around the application data so the relevant HATEOAS links can be included with each collection item. In a collection the “links” attribute may not include all of the applicable HATEOAS links but at minimum a “self” link will be provided with each collection item. 

"HVACSystems": [
    { "links": [
            { /* every collection should have a “self” link */ },
            { /* optionally a few more links */ },
        ],
        "HVACSystem": { /* application data, typically an abbreviated representation */ }
    },
    {  /* More collection items... */ },
    {  /* More collection items... */ },
    {  /* More collection items... */ }
]

GeoJSON resources

GeoJSON resources are provided as a GeoJSON feature or feature collection. All GeoJSON resources contain the same data as standard JSON resources, with additional geospatial data. The exact placement of “links” and “navTrail” attributes may vary in GeoJSON resources.

In some cases the CoolCalc GeoJSON resources may extend the GeoJSON spec with first level attributes such as “links”, “navTrail” or “collectionName”. These attributes are provided for interoperability with the CoolCalc client side libraries.

Examples

A first level REST resource for an individual piece of application data: 

{
    "HVACSystem": {
        "HVACSystemId": 123,
        "projectId": 456,
        "HVACSystemName": "A cool system"
        /* ... additional properties here .. */
    },
    "status": { "status": "ok", "errorMsg": "" },
    "navTrail": [
        ...
        ],
    "links": [
        ...
    ]
}

A first level REST resource for a collection: 

{
    "HVACSystems": [
        { "links": [
            { /* every collection should have a “self” link */ },
            { /* optionally a few more links */ },
            ],
        "HVACSystem": { /* application data, typically an abbreviated representation */ }
        },
        {  /* More collection items... */ },
        {  /* More collection items... */ },
        {  /* More collection items... */ }
    ],
    "status": { "status": "ok", "errorMsg": "" },
    "navTrail": [
        ...
        ],
    "links": [
        ...
    ]
}

A GeoJSON feature collection: 

{ "links": [ /* Same HATEOAS links as in a standard JSON resource or collection */ ],
    "navTrail": [ /* Same nav trail as in a standard JSON resource */ ],
    "status": {"status":"ok", "errorMsg":""},
    "collectionName": "rooms",
    "type": "FeatureCollection",
    "features":[
        { "type": "Feature",
        "geometry":{
            "type": "Polygon",
            "coordinates": [ … ]
        },
        "properties":{
            "links": [ /* Same collection item links as in a standard JSON collection item */ ],
            "room": { /* Same application data as in a standard JSON collection item * / }
        }
        },
        {  /* Additional GeoJSON features here … */  },
        {  /* Additional GeoJSON features here … */  }
    ]
}
Previous topic
Rest API Examples
Next topic
Customizing your CoolCalc installation