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 <https://github.com/lahmatiy/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)

.. _webapp_certificate:

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 :ref:`security_cors`),
- The application public key for the proprietary authentication scheme (see :ref:`security_auth`). 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:

.. code-block:: html

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

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