Quick reference

...

< https://... /products?type=show&offset=10&limit=10>; rel="previous"

X-Total-Amount: 254

Cross-origin support

For security reasons, browsers prohibit AJAX calls to resources residing outside the current origin. Cross-origin resource sharing (CORS) is a W3C specification implemented by most browsers that allows to overcome these limitations by authorizing access to different domains. CORS is automatically enabled in the servlet used by the RESTful API, and allows an unrestricted access from all domains to all resources. The supported HTTP methods are the following: GET, POST, PUT, PATCH, DELETE and HEAD.

To enable the cross-origin support, the Origin header must be set in the request, and indicate the current host that is accessing the resource. The response headers will then automatically be enhanced to contain the information required to authorize cross-origin in a browser. For more information, please refer to the following guide: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

SSL encryption

Only requests made on https will be handled. Requests sent to http will not be redirected, but result in error status 404.

Session handling

Sessions continue to exist on the server side as in the current ticketshop and are created when required. When a session is created, an X-auth-token header is returned, containing the unique session token string. To perform actions for this session, the client must in turn include this header in any request.

Context handling

The Secutix point of sale on which the purchase is made is specified by the custom header X-Secutix-Host, which takes the form of a POS-specific token that is provided to the client. All requests to the API must contain a valid context header, if not a 400 Bad Request response is returned.

Secutix contains a number of contact-specific catalog data, such as advantages and prices. When a user is logged in, none of the API endpoints will make implicit use of this context, except to check the user is authorized to perform any requested actions (such as viewing an order). Endpoints returning contact-specific values will require the contact number to be explicitly passed as parameter (of course, with checks that the logged-in user has indeed the rights to access this data). 

Internationalization

The RESTful interface supports internationalization. The external languages defined in the Secutix configuration screens determine which language can be used with the interface for every point of sales.

The language used to respond an API call, is either determined automatically or can be forced for every call. When a query parameter lang=xx (xx being the ISO-639 code of the language) is supplied, the response of the call will be translated in the given language code (if accepted by th e point of sales). When this parameter is not supplied, or it is not accepted, then the content of the Accept-Language header is checked against the accepted languages. If the language is not accepted by the point of sales, then the default language is used (i.e. the first language set in the configuration).

Versioning

The API is versioned, with the version appearing in the URL, such as /v1/products or /v2/products. A published version does not change, meaning the exposed DTO formats are unchanged and only backwards-compatible bug fixes are allowed (corresponding to patch versions in the terminology of the guidelines at http://semver.org/). As well as numbered versions, an “experimental” version containing the latest features is available under /vexp/products. Backwards-compatible changes of the latest versioned API will be published on the experimental version in production. The new frontend servers will use the experimental version.

...