Rest API


The CoolCalc applications expose nearly all of their functionality directly to client applications via the CoolCalc API.

In many cases you will not need to interact with the CoolCalc API directly. To integrate the CoolCalc applications in your web site or app there is usually no need to make any direct requests to the CoolCalc API. The CoolCalc libraries provide all of the necessary integration and abstract away the underlying API functionality.

Direct integration with the CoolCalc API is required when you have other applications that need to share data or interact with the CoolCalc API. Examples of use cases where you would interact directly with the CoolCalc API include creating MJ8 projects in CoolCalc based on data from your lead generation tools, directly linking MJ8 reports to proposals in a proposal tool, creating AHRI matchups in CoolCalc based on the contents of a user's shopping cart, etc.

In "the real world", 2 of the key objectives of the CoolCalc applications are data sharing across organizational boundaries and long lived, flexible work flows. In order to implement these objectives, the CoolCalc API was designed as a true REST API, including navigation based on HATEOAS links. For the benefit of developer experience we recommend reviewing the section on REST vs FIOH below.


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:

"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period."

"... the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword for your API."

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.

  • (*) Acronym slightly modified from the original.
  • (**) As an example, the underlying MJ8 procedure for the CoolCalc Manual J application is a 600+ page book.


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.

Error handling

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."}}

API domains and versions

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 and version "staging" (in the REST URL).
  • For the production API, use and version "current" (in the REST URL).

API entry points

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.

  • Staging:
  • Production:

The entry point for the MJ8 project list:

  • Staging:
  • Production:

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

  • Staging:
  • Production:

HTTP Methods

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

  • GET: read a resource
  • POST: create a new resource (add-to-collection)
  • PUT: update an existing resource
  • DELETE: delete a 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.

Note: 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 libraries are designed so clients never have to manipulate API resources any more than setting individual attribute values. The format of the resource as received from the API should be the same as that of the resource returned to the API. Not withstanding the foregoing, at the API the PUT method is actually implemented more as a PATCH method, ie. if the client only supplies a partial resource (payload) all other attribute values will be reused from the existing resource.

HTTP Headers

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.

URL query parameters

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.

Note: Required URL query params must be present regardless of the HTTP method used. See section on sample API calls for details.

Creating new resources

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.

Resource names

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.

Previous topic
User Interface