The documentation for this API provides a detailed description of the available endpoints with examples of the responses obtained, as well as information
about their usage.
Some prior considerations to take into account are:
-
The API uses JSON Web Tokens for authentication.
-
API requests must be made with GET o POST requests as appropriate.
-
All responses that are not returned with an HTTP 200
code can be considered an error.
-
All responses are returned in JSON format.
Version
The versioning of the API is determined in the URL itself. For example, for
version 1 we will get the following URL:
{baseUrl}/v1/xxx....
Authentication
-
As a previous step to obtaining the token, you must have the security
certificate and that the IP is on the allowed list.
-
The cn that is contained in the certificate that is used is the one that the application uses to check if it exists in the user registry.
{baseUrl}/v1/token
-
If the authentication is valid, a response is obtained with the date and time in UTC format when it was generated, when it expires and the token itself.
{ "issuedAt": "2021-04-01T09:09:16.284Z", "expiration": "2021-04-02T09:09:16.284Z", "token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......." }
-
Also, if a request is made with an expired token, an HTTP 400 – Bad Request error is received with the response as in the following example. A new token must be requested to continue making requests to the API.
{ "status": 400, "code": 6, "message": "Expired token received" }
-
To make requests to the API endpoints, an attribute must be attached to the request headers in the header (Authorization) and its value will be Bearer (the type of token obtained) plus the value of the token that you have obtained separated by a space. For example:
Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJDTW9iaWxpdHkzLjAiLCJzdWIiOiJwcnVlYmEiLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwiaWF0IoxNjE2NDIxMDYyLCJleHAiOjE2MTY0MjQ2NjJ9.N8KimN9_IgtjXX2Wv-rXLKK929mavlkaakxY_NzHVFgN9DWT8bqRVeTaBgL5GbzDfZSPZXDutoVwjdbTEx3FbA
Errors
As stated above, all HTTP responses other than 200 – OK, can be considered invalid. The format of the error response is like the following example:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
These errors will have three main categories:
Authentication Error
-
HTTP Status: 401 - Unauthorized
Code Message 1 User not found or valid
Client Error
-
HTTP Status: 400 - Bad Request
Code Message 0 Authenticate 2 Entity ID not found 3 Missing required property 4 The entity received cannot be proccessed 5 Incorrect token received 6 Expired token received 7 There is an error with the token provided. Please request a new one 8 No token received 9 Required request body is missing 10 Event is marked as expired by timestamp
In the case of getting an error 3 - Missing required property, the response obtained will have a value in the message that will indicate the missing fields to send:
{
"status": 400,
"code": 3,
"message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
}
Server Error
-
HTTP Status: 500 - Internal Server Error
Code Message 11 Internal error
Swagger
The application has a Swagger auto-generated by the code itself where the different endpoints can be found.
{baseUrl}/swagger-ui/index.html