| Warning |
|---|
This API is not public anymore. Existing endpoints are maintained, but no support will be provided for new integrations. |
Quick reference
The reference of public Gravity REST API endpoints is available at the link above.
Every endpoint is described and the required parameters are presented. A graphical interface allows to test every endpoint and consult the Models used by the interface.
Usage notes
Currently, REST APIs are still coupled with internet points of sales. This means, that calls done on the REST API, must be performed starting from the internet URL, and are accessible through the following URL pattern:
https://<point of sales url>/tnwr/v1/
This will be subject to change in future versions, which will be hosted in a separated and centralized environment. The context parameter, set in the header X-Secutix-Host (see Context handling section below) is required but redundant right now, but will allow in the future for a seamless migration to the new API hub.
Introduction
This document presents the architectural principles of the Gravity REST API and provides information about its usage. This API is incomplete and will progressively be enhanced in parallel to the Gravity (FMR-LINK) project.
This REST interface is a compliment an addition to the already existing interfaces provided by SecuTix. It is an interface that works at a higher level than the interfaces provided by the back-end services. Its goal is to provide a simple set of entry points that aggregate all the information required for a front-end implementation, and that allow the user interactions involved in a ticketing purchase process. As an example, the catalog entry points return products that are pre-processed: they contain the right availabilities, propose prices that are accessible to the specific user and offer all information that is required for user interaction. User interactions, like adding a ticket to the shopping cart, are simplified and executed through calls to the interface.
...
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).
...
The specifications presented in the following chapters are not completely implemented in the current version of the Gravity REST API. They are meant to be used as general guidelines and provide an overview of the future implementation of this API.
...
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 is aliased (i.e. a new action with abstraction of parameters).
...
In addition, the HTTP status code of any unsuccessful call is taken from among the following:
HTTP error code | Meaning & use cases |
|---|---|
400 – Bad request | Request parameters passed with the request are missing or incorrect |
401 – Unauthorized | The action requires authentication and sufficient permission levels for the contact |
403 – Forbidden | The action is not allowed for the current contact (not enough privileges) |
404 – Not found | The resource targeted with the action does not exist |
415 – Unsupported Media Type | The request is not in the correct format, or the Content-Type header is not set accordingly. |
500 – Internal server error | An unforeseen server error occurred |
In the case an internal server error occurs, the error is logged to ease the follow-up of the issues. All other errors are not logged. In addition a 500 error response will always include fields to indicate whether the user was logged out and/or if the order was cancelled, allowing the client to correctly handle the following steps.
...
Filtering requests can be done by adding supported fields as request parameters, for example to request all tickets in status printed:
GET /tickets?status=printed
The API documentation will specify precisely for which fields filtering is supported. Initially no more advanced search functionalities will be provided (such as “or” operators or more advanced text searches).
...
Pagination is done following established standards for handling this case. Any endpoint providing pagination supports the offset and limit parameters, specifying at which record to start and the maximum number of records to return (if these are not provided, it defaults to 0 and 20). The total amount of records is always returned in the X-Total-Amount header. 4 links are also returned in the Link header, pointing the client to other useful subset of the collection. For example, the following request for products of type “show”:
GET /products?type=show&offset=20&limit=10
Assuming we have say 254 show products available, the response body then contains 10 products starting at position 20 (the internal list may be ordered by product name for instance):
{success:true, data: {“123”:{code:”product1”, startDate:”2016-12-20T17:30Z”, …}}
Whilst the response headers are set as follows:
Link: <https://... /products?type=show&offset=30&limit=10>; rel="next",
< https://... /products?type=show&offset=250&limit=10>; rel="last",
< https://... /products?type=show&offset=0&limit=10>; rel="first",
< 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, 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. A restriction can be configured in SecuTix, to authorize only specific domains.
...
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.
...