Server Side Library

In the CoolCalc data store all data is segregated by API customer and additionally by the unique id(s) for the end user, which are provided in the REST URL. The CoolCalc API never sees identifiable end user information such as names or email addresses.

The server-side library implements 2 essential responsibilities related to data privacy:

• Provide the API customer's credentials (ie. your organization's credentials) in all requests to the CoolCalc API.
• Verify the end user's unique id(s) in the REST URL in all requests to the CoolCalc API.

User interaction in the CoolCalc user interface triggers XHR requests from the browser to your local server, by means of the CoolCalc JavaScript library. The server-side library effectively forwards the XHR requests from the browser to the CoolCalc API and forwards the response of the CoolCalc API to the browser. For example:

• Browser requests URL on your local server:
  • https://www.your-domain.com/coolcalc/client/current/dealers/12345/MJ8Projects/
• The server-side library repeats the request to:
  • https://api3.coolcalc.com/current/dealers/12345/MJ8Projects/
• The server-side library forwards the response from the CoolCalc API to the browser.

Your server as the identity provider knows and authenticates its end users. The contract between your server and the CoolCalc API is simply that the user identification provided in the REST URL is valid. For example, in the sample API request below your server is guaranteeing to the CoolCalc API that the end user account nr is "12345":

• https://api3.coolcalc.com/current/dealers/12345/MJ8Projects/

After the initial URL segment that contains your customer account nr. the CoolCalc API verifies foreign keys for all subsequent URL segments to prevent Insecure Direct Object References (IDOR).

A frequent question from API customers and developers is why does CoolCalc require a server-side library and why not use CORS?

The reason is simple: CORS is typically used to do the opposite of what the CoolCalc API does. With CORS, any site (your-domain.com) can make credentialed requests to a different domain, which is typically an identity provider. If all end users of our various API customers were logged in on a CoolCalc domain the browser could use CORS to make credentialed requests from your-domain.com to CoolCalc. However, that is not how CoolCalc is designed. End users are known to and authenticated by our various API clients (your-domain.com) but entirely unknown to the CoolCalc API other than by the unique IDs that your-domain.com provides for each end user.

The above is not a programming constraint but a key part of the real-world, commercial value of CoolCalc. OEMs and distributors integrate with CoolCalc to add value to the relationship with their own customers. The end users enjoy the benefits of the CoolCalc applications without being a direct or first-degree CoolCalc customer.

In a typical installation the local server-side library exposes the following endpoints:

• A user identification endpoint to provide end user identification for the current session to the CoolCalc JavaScript library.
• The main “CoolCalc client” endpoint that forwards XHR requests from the browser to the CoolCalc API.
• A dedicated “MJ8 report” endpoint that forwards only XHR requests for the MJ8 report resource to the CoolCalc API.
• A special purpose endpoint for HTML to PDF conversion.
• A special purpose endpoint to email MJ8 reports to users.

Each of the endpoints is documented in the following sections. The sample client side libraries in our Github repository include boilerplate code for these endpoints but in most cases some internal details will need to be implemented on your side because the specifics of session and user management may vary in each client's existing code base.

Optionally, if you want to implement local or custom REST resources above and beyond the REST resources provided by the CoolCalc API, your local server-side library needs to implement an additional endpoint that provides the static HTML for those resources to the CoolCalc JavaScript library. See the section on customizing CoolCalc for further details.

The CoolCalc user interface normally opens on the user's project list. As part of the user interface initialization, the CoolCalc JavaScript library queries a local endpoint on your server for the end user's identification. With the end user's identification, the JavaScript library constructs the entry URL for the user's project list and then makes the initial API call.

From the web root, the typical location for the end user identification endpoint is:

• ASP: /coolcalc/user/{version}/session-user.ashx
• Java: /coolcalc/user/{version}/SessionUser
• PHP: /coolcalc/user/{version}/session-user.php

The output of the end user identification endpoint must be a JSON string as follows:

{ “userReference”: “12345”, “dealerReference”: “xyz-345-abc”, “isAdmin”: true }

If the boolean isAdmin is true the user will have access to all projects of all individual end users in their organization. If isAdmin is false, the user only has access to their own projects.

As explained in the data privacy section, one of the principal responsibilities of the server side library is forwarding the XHR requests from the browser to the CoolCalc API. A single endpoint on your local server is used to forward all browser requests for a given entry point at the CoolCalc API. Currently, all requests except for direct requests to an MJ8 report resource are based on the “/dealers” entry point.

From the web root, the typical location for “dealers” endpoint is:

• ASP: /coolcalc/client/{version}/dealers.ashx
• Java: /coolcalc/client/{version}/dealers
• PHP: /coolcalc/client/{version}/dealers.php

When initializing the user interface, the CoolCalc JavaScript library queries your end user identification endpoint to download the user's project list. The JavaScript library will make all subsequent API requests based on the entry URL that contains the user's identification. However, this is done in the client (browser) and nothing can be done to prevent a dishonest user from manually entering a URL with a different account nr in the browser, thereby downloading the project list for another user.

To avoid such an exploit, the server-side library must verify that the customer identification in the REST URL corresponds to the current session user before making any HTTP requests to the CoolCalc API.

In “the real world” it is often necessary to access an MJ8 report outside the normal flow of the CoolCalc user interface, for example, for PDF conversion, email or link sharing.

However, the design of the CoolCalc applications – specifically the data privacy mechanisms explained in this chapter – prevent sharing any resources from the user interface without a valid session. Put simply, nobody can access any resource in the CoolCalc UI without proving they are the owner of that resource.

To allow MJ8 report access without an existing session while providing an acceptable measure of data privacy, MJ8 reports are identified by unique, not guessable ids and the server-side library implements a dedicated endpoint for MJ8 report resources. This dedicated MJ8 report endpoint differs from the main CoolCalc client endpoint only in that it does not require a valid session and returns only the MJ8 report resource by unique ID.

From the web root, the typical location for the MJ8 report endpoint is:

• ASP: /coolcalc/client/{version}/mj8-reports.ashx
• Java: /coolcalc/client/{version}/MJ8Reports
• PHP: /coolcalc/client/{version}/mj8-reports.php

Your web server should map all requests based on a “/coolcalc/client/{version}/dealers/...” URL to this endpoint, regardless of the URL segments following the “/dealers” segment.

The MJ8 report endpoint is implemented in each of the sample client side libraries in our Github repository. In most cases no configuration or implementation is required on your side.

The static HTML for the downloadable MJ8 report is hosted on the client's server for the purposes of customization and branding. HTML to PDF conversion must be implemented on the client side.

The section on customizing CoolCalc provides a complete overview of the HTML to PDF implementation. In a typical installation, the server-side library implements a dedicated, special purpose endpoint to convert HTML to PDF. The CoolCalc JavaScript library automatically invokes this endpoint and provides the HTML URL to be converted in the body of a POST request.

As with PDF conversion, the email/share functionality of the MJ8 report must be implemented on the client side.

The section on customizing CoolCalc provides a complete overview of the email/share report implementation. In a typical installation, the server-side library implements a dedicated, special purpose endpoint to email the MJ8 report in PDF format. The CoolCalc JavaScript library automatically invokes this endpoint and provides the HTML URL of the report as well as the desired “email to” address in the body of a POST request.