Rest API

The academics of REST are beyond the scope of this documentation. However, to understand the CoolCalc API it is helpful to consider that the CoolCalc API attempts to be a true REST API, specifically using HATEOAS links to achieve loose coupling between clients and server.

It's a matter of fact that many APIs which are loosely advertised as RESTful do not implement the REST architectural style as originally set forth in the Fielding dissertation. Specifically, many APIs that are loosely advertised as RESTful do not implement HATEOAS links but rather HTTP requests based on known, hardcoded endpoints.

Different architectural styles each have their own merits and the design of different APIs is entirely up to each development team. However, it's the experience of this development team that the proliferation of the term REST in relation to APIs that are not at all RESTful has contributed to poor developer experience when implementing APIs that do attempt to be truly RESTful, such as the CoolCalc API.

The raison-d'etre for this rant section then is an attempt to improve developer experience by illustrating that the CoolCalc API is significantly different from what may be the pre-existing notions of REST in the experience of many developers.

In his blog Roy Fielding elaborates on the idea that HATEOAS is a fundamental constraint in the REST architecture:

More recently "Two bit history" has proposed the term "FIOH" as an API architecture buzz word. As in "Forget about It, Overload HTTP already"(*). In fact, most APIs loosely advertised as REST are doing exactly that: they are an HTTP based web service where clients use a set of published end points and pre-existing knowledge of the application's underlying use case(s) to implement the application logic, ie. knowing when and how to navigate from endpoint to endpoint.

For the benefit of developer experience it may be helpful then to illustrate the key differences between the CoolCalc API and FOIH style APIs, as these differences may affect integration with clients:

• Unlike FOIH style APIs the CoolCalc API does not publish endpoints for all of the various resources exposed by the API.
• Instead, clients should enter the API at the published entry points for the various applications and navigate the API by following the HATEOAS links provided with each resource.
• The CoolCalc API exposes many different endpoints(**) and workflows that may change over time.
• In FOIH style APIs clients navigate based on pre-defined endpoints, known resource names and shared knowledge.
• In the CoolCalc API the HATEOAS link relations (implemented as a "rel" attribute) provided by the server are the basis of navigation and application flow at the client.

It could be argued that there are no standard client side libraries to consume HATEOAS driven APIs, which is largely true. To mitigate this issue, CoolCalc provides client side libraries and cloud based user interfaces (which are also HATEOAS driven) to deploy in your client applications.

Clients may navigate the entire body of resources exposed by the CoolCalc API by following HATEOAS links provided with each resource but in most cases direct API calls from client applications will be limited to the published entry points of the API or first-degree dependencies thereof. More deeply nested resources are rarely relevant in direct API calls to client applications.

The CoolCalc API uses HTTP Basic authentication. The username is your API client id and the password a unique API key assigned to your API client id. API clients are responsible for maintaining their API credentials secure and notifying CoolCalc administrators should their API credentials become compromised.

The CoolCalc API accepts only connections over HTTPS, connections over HTTP will receive an HTTP “303” response with redirect to the corresponding HTTPS URI.

Standard HTTP status codes are used to indicate the status of each request. 400 and 500 series status codes indicate errors occurred processing the request. If an error occurred, a first level "status" property in the JSON response should include a detailed error message.

Ordinary client or server errors typically return human readable error messages. Broken or malformed URLs may result in cryptic error messages as the API considers those types of errors possibly related to security.

{"status":{"status":"error","errorMsg":"Nilo Castaneda, FC Cienciano."}}

The CoolCalc API provides a semi-perpetual “current” version for production and a semi-perpetual “staging” version for the staging API. Should any breaking changes be introduced in the future, numbered “frozen” versions will be provided for those customers who wish to stay on a previous version.

• For the staging API, use https://stagingapi.coolcalc.com and version "staging" (in the REST URL).
• For the production API, use https://api3.coolcalc.com and version "current" (in the REST URL).

The following API entry points exist as part of the CoolCalc Manual J application. Clients should not construct REST URLs manually other than the initial API entry points. All other requests should be made by following the HATEOAS links that the API provides in the "links" attribute of each resource.

Currently all API requests except MJ8 reports are based on the “dealers” collection entry point.

The entry point for the MJ8 project list:

A special purpose MJ8 report endpoint is normally used to download MJ8 reports by their unique ID, outside of the normal application flow.

The CoolCalc API implements standard HTTP methods as follows. These methods implement the same action regardless of the specific resource:

Not all methods are allowed on every resource. Each resource downloaded from the CoolCalc API includes an HTTP "Allow" header which indicates the allowable methods on the given resource. Clients can use the value of the "Allow" header to implement controls for the resource in the user interface. If a client makes a request using a method not allowed for the specific resource the server will respond with a 405 error code.

All API requests should include an HTTP "Accept" header with value "*/*". Future implementations may return distinct content based on the HTTP "Accept" header provided by the client (eg. JSON vs. GeoJSON). It's recommended (but not necessary) to set a Content-Type header for PUT and POST requests.

The CoolCalc API provides an HTTP "Allow" header in each response. The HTTP “Allow” header is used by the CoolCalc JavaScript library to implement the user interface. It is rarely necessary for clients to refer to the HTTP "Allow" header outside of the CoolCalc JavaScript library.

Currently the API returns all resources in JSON or, if applicable, GeoJSON. The Content-Type header provided by the server will indicate the content type for each specific resource.

A few API URLs include required URL query params. If the REST API responds with a 300 series response code, you should follow the redirect. This is normally the case when a required URL query param is missing. When any required URL query param is missing the server will redirect to a new URL with default value(s) for all required URL query params.

The CoolCalc API provides HATEOAS links with each resource to allow the client to interact with the resource and its dependencies without the use of hard-coded end points.

At this time the concept of JSON linking in REST APIs is relatively undefined. Several libraries exist for JSON linking but there is no one accepted standard. The CoolCalc API uses a custom format which adds a "links" attribute to each REST resource. The "links" attribute is an array of HATEOAS links directly related to the given resource. Additionally each resource contains a "navTrail" attribute which consists of the HATEOAS links specific to any higher level URL segments, which allows the user interface to construct the complete navigation from any resource to any earlier point in the navigation/flow.

CoolCalc HATEOAS link example:

{"href":"https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2218/outdoorDesignConditions",
    "rel":"outdoorDesignConditions",
    "resourceName":"outdoorDesignConditions",
    "title":"Design Conditions",
    "description":"Raleigh-Durham IAP 92F / 23F",
    "status":"Default"
}

The CoolCalc HATEOAS link format includes the following attributes:

• rel: the relation of the linked resource to this resource.
• resourceName: the unique name of this resource.
• href: the URL of the resource. May be empty if the linked resource is not yet available.
• title: a human readable link title.
• description: a human readable description.
• status: the status of the linked resource.

The "status" attribute of a HATEOAS link may have any of the following values:

• "Default": The resource was completed with default data provided by the API. This is typically used for resources that are not part of the required flow (optional). The user may navigate to this resource.
• "Complete": The resource is complete with data provided by the client. The user may navigate to this resource.
• "Pending": The resource is not yet complete but all prerequisites are complete, or the resource has no prerequisites. The user may navigate to this resource.
• "Disabled": The resource is not yet complete and some prerequisite(s) are incomplete. The user may not navigate to this resource.
• "Obsolete": The resource was complete at one time but the data is now obsolete. The user may navigate to this resource.
• "Show always": A special status for resources that are not normally manipulated by end users but rather provide some utility functionality such as available options for HTML form fields.

All of the resources provided by the CoolCalc API are identified by a unique resource name ("resourceName" attribute). For each dependency a HATEOAS link will be provided with the "rel" attribute corresponding to the "resourceName" attribute. Conceptually these are navigation links in the UI.

In addition to the HATEOAS links based on unique resource names, the CoolCalc API also provides the following boilerplate HATEOAS link rels. Conceptually these are links that are used to manipulate this resource and implement application flow.

For HATEOAS links with one of the below boilerplate rels, the "resourceName" attribute will indicate the actual resource name of the referenced resource:

• self: the URL of the current resource.
• parent: the URL of this resource's immediate parent.
• collection: for resources that have a logical 1-to-many relation with their parent, the URL of the collection.
• next: the logical next step in the sequence (if a collection, the next page).
• incomplete: the nearest incomplete step in the process.
• template: a new resource template for collections that implement "add-to-collection".

A few collections (e.g. MJ8Projects) implement pagination. Collections that implement pagination provide HATEOAS links for pagination with the following link rels: "first", "last", "next", "previous" and "all".

Collection items are usually an abbreviated representation of the underlying resource. Like first level REST resources, each collection item includes a “links” attribute. Not all link relations may be present in collection items but at minimum each collection item should provide a “self” link. To download any item in a collection the client only needs to make a GET request to the item's “self” link.

When new resources can be added to a collection, the collection will provide a "template" HATEOAS link and the HTTP "Allow" header provided with the collection should include a "POST" method. By convention, the template link URL is that of the collection with an additional "/0" URL segment.

It is not recommended that clients construct their own payloads. Instead clients should download the new resource template for the given collection, edit only the individual attributes as required, and then make a POST request to the collection URL with the updated template (which is now no longer a template) as the payload.

The output of a POST request, if successful, which will return the updated collection and an HTTP 201 status code. The newly created item is not returned as the output of the POST request, instead, an HTTP “Location" header in the response to the POST request will indicate the location of the newly created resource. Clients only need to perform a GET request on the URL specified in the HTTP “Location” header in order to download the newly created resource.

Resources provided by the API may change at the relative whim of the developers and/or based on changes in the underlying application flows, for example due to revisions in the Manual J or Manual S standards. If or when resources change, the static HTML on the CoolCalc CDN will be updated concurrently with any API changes so rendering in your user interfaces will not be affected.

The CoolCalc API exposes nearly all of its functionality via HATEOAS links but client applications are typically only interested in a few high level resources for the purposes of integration. The following are commonly requested resource names that are first or second degree dependencies of the API entry points:

• MJ8Projects: A collection of MJ8 projects, specific to a given dealer id (account nr) and optional end user (individual) id.
• MJ8Project: A single MJ8 project.
• constructionDetails: The construction details for a given MJ8 project.
• dimensions: The dimensional data for a given MJ8 project.
• HVACSystems: A collection of HVAC systems for a given MJ8 project.
• MJ8Reports: A collection of Manual J reports for a given project.
• MJ8Report: The MJ8 report for a single HVAC system.