...
As an example scenario, a Ticket could allow for two actions: one to retrieve its content and one to set the beneficiary. In this case, the endpoints could be defined as follows:
| Endpoint | Description |
|---|---|
| GET /tickets |
...
| retrieves the information of all tickets associated to the connected user | |
| GET /tickets/123 |
...
| retrieves the information for the ticket with id 123 | |
| PATCH /tickets/123 | (with additional form data {first name, last name} passed in the request body as JSON, see below for request format): sets the beneficiary of ticket 123 |
Notice that the same endpoint can allow for different granularities (in the example above, the complete list of tickets and a specific ticket).
REST API specifications
Endpoint definition: convention and supported HTTP methods
As described in the previous section, the definition of an endpoint must be linked to a resource name. As a convention, the name of a resource is defined with a plural lowercase noun. Moreover, the correct mapping method must be used to define every action that applies to the selected resource (CRUD mapping to HTTP methods).
The following table shows the supported HTTP methods and for which kind of action they are used:
...
| Operation | HTTP method |
|---|---|
Create | POST |
Read | GET |
Update | PUT (complete data) - PATCH (partial data) |
Delete | DELETE |
As a convention, parameters required for actions on particular resources (for instance actions applied to a specific ticket in the previous example), are defined as path variables. Query parameters are only used to refine the request (like filtering or sorting). When a frequently used action requires the setting of specific parameters, then it should be aliased (i.e. a new action with abstraction of parameters).
Warning: actions must be configured with the adequate security settings, based on the requested user privileges (see chapter about security and authentication for more information).
Format of requests
For POST/PATCH/PUT requests, the content of the modifications should be sent in the request body in JSON format, with the Content-Type header set to application/json (if the header is not set a 415 Unsupported Media Type response should be returned).
Format of responses
The Secutix RESTful API supports a single response format: JSON. All response objects are serialized in this standard format. As a guideline, objects returned by the API should be as flat as possible and easy to access by a front-end. Moreover, when handling requests that potentially return many objects, a strategy based on paging should be applied. The naming of the fields is also important: meaningful and consistent naming is highly encouraged.
...
In general, a request that is modifying some resource (PUT, PATCH, POST) should return the complete updated resource in the response.
Error handling
As already mentioned, every response object of the API will contain a success field. Whenever an error occurs, the success field is set to false, and an error code and message are returned (these are always set).The error message is destined for the user of the API (not the end user of the web application). The error code can be looked up in the API documentation for details of the error (see ???) and can be used by the frontend implementation to determine the error message to display to the user. For these reasons, the error code should be as specific as possible.
...
Comment for developers: any Java response class should extend the provided RestReponse class, which already provides all the error handling fields described above {success: boolean, errorCode: int, errorMessage: string, orderReset: boolean, userLoggedOut: boolean}.
Filtering, sorting, searching and pagination
Filtering requests can be done by adding supported fields as request parameters, for example to request all tickets in status printed:
...
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.