Using the API

Prerequisites

The SCWS API depends on some JavaScript features not available in all environments. The following APIs need to be available:

  • The XMLHttpRequest API, in order to make dynamic HTTP requests from JavaScript.

  • The FormData API, which allows to construct MIME multipart HTTP POST requests.

  • The ArrayBuffer API, which allows manipulating binary data.

  • The Promise API, used extensively to handle asynchronous requests in a practical manner. For this specific requirement, a polyfill can be used on browsers that do not support this API natively (a suggested implementation is es6-promise-polyfill).

Moreover, in order to be able to call the local SCWS service from an application served by an HTTPS connexion, there are some additional constraints to consider, due to mixed-content restrictions. Browsers typically don’t allow a page served from HTTPS to perform AJAX requests through HTTP. On some modern browsers (latest Chrome and Firefox), an exception is made when the request is made locally to 127.0.0.1. For the other browsers, the request is made through HTTPS to circumvent this restriction: the SCWS service supports it, but it requires the browser to check the certificate validity against the system stores (this is the case for most browsers, the notable exception being Firefox).

As a consequence, the browser compatibility table is:

  • Internet Explorer 11 (requires a Promise polyfill)

  • Edge all versions

  • FireFox 55+ (29+ if mixed-content do not apply, 4+ with a Promise polyfill)

  • Chrome 33+ (7+ with a Promise polyfill)

  • Safari 8+ (5+ with a Promise polyfill)

  • Opera 20+ (12+ with a Promise polyfill)

Web Application Certificate

For a web application to be allowed to contact the SCWS, Idopte provides the customer with a web application certificate, under the form of a static character string. This certificate encodes the two necessary parameters for ensuring only authorized applications access the SCWS:

  • The application server base URL (eventually with multiple synonym domains), used for the CORS mechanism (see Cross-origin restriction),

  • The application public key for the proprietary authentication scheme (see Proprietary authentication scheme). The key pair is generated on the customer’s side and the private key only need to be known on the customer’s web application server.

Customers must provide these two pieces of information when requesting Idopte to generate a web application certificate.

Integration

Using the API from a web page simply requires including the provided script:

<script src="scwsapi.js"></script>

After which the SCWS object, which acts as a namespace for all the API entry points, is available globally.