Rest API Examples

CoolCalc provides a live demo site representative of a typical HVAC distributor at atix-hvac.com. You may use the credentials of the Atix HVAC site for the REST API examples in this chapter so you can immediately see the results of the requests in the Atix HVAC user interface.

In addition to the API customer credentials provided in the HTTP Basic authentication the end user is identified by dealer id (account nr) in the REST URL and optional individual user id as a URL query param. The Atix HVAC site has 3 hardcoded users with the ids given below. Use any of the user information given here in your API requests to see the result of the API requests in the Atix HVAC user interface.

HTTP Basic Authentication is required. You may use the Atix HVAC credentials (above) or if you already have your own API credentials feel free to substitute your organization's API credentials.

The sample API requests in this chapter are made to the CoolCalc staging API. API credentials are different for the CoolCalc staging and production servers. To state the obvious, production applications must use your organization's API credentials.

The main entry point of the CoolCalc MJ8 application is the project list. The project list URL accepts the following URL query params:

• dateRange (required)
• linesPerPage (required)
• pageNr (required)
• userId (optional)
• address, city, state, country (all are optional but if any is provided all 4 should be provided)
• latitude, longitude (both are optional but if either is provided both should be provided)
• maxDistance (optional, recommended if address or geolocation are provided)

CoolCalc REST API example: Download the MJ8 project list for account nr “1626443386”, all users.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/?dateRange=90+days&linesPerPage=10&pageNr=1" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

CoolCalc REST API example: Download the MJ8 project list for account nr “1626443386”, individual user id “2”.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/?dateRange=90+days&linesPerPage=10&pageNr=1&userId=2" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

Clients can search for projects near a location or address by providing the address or geo-reference (latitude/longitude) URL query params. It's recommended to search by geo-reference over address params. If address params are provided the CoolCalc API will attempt to geocode the given address but this is a best effort only and correct geocoding cannot be guaranteed.

CoolCalc REST API example: Search for projects for account nr “1626443386” near a specified address.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/?dateRange=90+days&linesPerPage=10&pageNr=1&city=Golden+Beach&state=FL&address=Ocean+Blvd&maxDistance=10" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

CoolCalc REST API example: Search for projects for account nr “1626443386” near specified latitude/longitude.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/?dateRange=90+days&linesPerPage=10&latitude=35.0476912&longitude=-90.028238&maxDistance=10" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

To create a new MJ8 project clients make a POST request to the project collection URL. Please note that required URL parameters must be included for POST requests – identical as in the corresponding GET request - or the server will respond with a 300-series redirect.

If successful, the output of the POST request is the updated project list, not the newly created item. The URL of the newly created item will be specified in the “Location” HTTP header in the response to the POST request. Clients may download the newly created item by making a GET request to the URL provided in the “Location” header.

We recommend that you construct the payload for the POST request based on the new resource template provided by the CoolCalc API. A new resource template may be obtained by making a GET request on the collection's “template” HATEOAS link. By convention the “template” URL is the collection URL followed by “0”. We recommend that clients do not attempt to construct new collection item payloads on their side but rather download the template and set the individual attribute values as required, then use the completed data structure as the payload for the POST request.

CoolCalc REST API example: Download new resource template for the MJ8 projects collection.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/0" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

CoolCalc REST API example: Create a new project for account nr “1626443386”, individual user id “2”.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/?dateRange=90+days&linesPerPage=10&pageNr=1&userId=2" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -X POST -d '{"MJ8Project":{"project":"Erics house","address":"461 Ocean Blvd","city":"Golden Beach","state":"FL"}}' -H "Content-Type: application/json" -H "Accept: */*"

From the project list, clients can download any project in the collection by making a GET request to the “self” link of the item in the collection:

CoolCalc REST API example: Download project with id 2129.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2129" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

Most of the time users will edit data in a CoolCalc user interface integrated in any of your applications. However, if there is a need to do so you can update data in the CoolCalc API by making a PUT request to the “self” link of any resource.

CoolCalc REST API example: Update project with id 2129.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2129" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -X PUT -d '{"MJ8Project":{"project":"A nice updated project oxoxo"}}' -H "Content-Type: application/json" -H "Accept: */*" -v

Other than the entry point of the MJ8 application, a commonly requested API resource is the MJ8 report. Clients that integrate applications such as proposal tools with the CoolCalc API may wish to link directly to an MJ8 report or MJ8 reports collection in the CoolCalc API.

The CoolCalc MJ8 application implements various flows to the MJ8 report. Note that a project in CoolCalc may have multiple HVAC systems and therefor multiple MJ8 reports. The MJ8 report is specific to an HVAC system but as a matter of convenience the CoolCalc API implements HATEOAS links to the MJ8 report from the project and HVAC system level:

• In any collection of MJ8 projects, each collection item (individual project) implements a HATEOAS link with rel=”MJ8Reports”
• Individual MJ8 projects implement a HATEOAS link with rel=”MJ8Reports”
• From the collection of MJ8 reports the client can navigate to any report in the collection by following its “self” link.
• In any collection of HVAC systems, each collection item (individual HVAC system) implements a HATEOAS link with rel=”MJ8Report”
• Individual HVAC systems implement a HATEOAS link with rel=”MJ8Report”

CoolCalc REST API example: Download MJ8 reports collection for project with id 2129.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2105/MJ8Reports/" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

CoolCalc REST API example: Download the MJ8 report for HVAC system with id 2440.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2105/HVACSystems/2440/MJ8Report" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

All of the above are normal application flows, repeatable in the CoolCalc user interface. In addition to the normal application flows, MJ8 reports may be downloaded by their unique id from a dedicated API entry point. The practical use case for this entry point is downloading MJ8 reports outside of the normal flow of the user interface, such as for MJ8 report email, PDF conversion or link sharing.

CoolCalc REST API example: Download the MJ8 report with id 44Y-1CP6-M6S.

curl "https://stagingapi.coolcalc.com/staging/MJ8Reports/?reportId=44Y-1CP6-M6S&rev=latest" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v

As a true REST API, the CoolCalc API does not publish a list of endpoints for all of its various resources. Instead, clients should follow the HATEOAS links provided in any resource to navigate to that resource's dependents. Work flows may change over time and run-time dependencies may change with different attribute values (user inputs) for any given resource.

Notwithstanding the above, some common HATEOAS link rels in the CoolCalc API include:

• “MJ8Projects”: the main entry point for the MJ8 application, the user's project list.
• “MJ8Project”: the landing page for any individual project.
• “HVACSystems”: the HVAC system collection for an MJ8 project.
• “HVACSystem”: an individual HVAC system.
• “MJ8Reports”: the MJ8 reports collection for a given project.
• “MJ8Report”: the MJ8 report for a single HVAC system.

CoolCalc REST API example: Download the HVAC systems list for project with id 2105.

curl "https://stagingapi.coolcalc.com/staging/dealers/1626443386/MJ8Projects/2105/HVACSystems/" -u AtixHVAC:"xxxxxxxxxxxxxxxx" -H "Accept: */*" -v