La documentación de esta API ofrece una descripción detallada de los métodos disponibles con ejemplos de las respuestas obtenidas, así como información acerca del uso.
Algunas consideraciones previas a tener en cuenta son:
-
La API utiliza JSON Web Tokens para la autentificación.
-
Las peticiones de la API deben ser realizadas con peticiones GET o POST según el caso.
-
Se pueden considerar todas las respuestas que no sean devueltas con un código HTTP 200 como un error.
-
Todas las respuestas son en formato JSON.
Versión
El versionado de la API se determina en la propia URL. Por ejemplo, para la versión 1 obtendremos la siguiente URL:
{baseUrl}/v1/xxx....
Autentificación
-
Como paso previo a la obtención del token, se debe poseer el certificado de seguridad y que la IP esté en la lista de permitidas.
-
El cn que está contenido en el certificado que se utiliza es el que la aplicación utiliza para comprobar si existe en el registro de usuarios.
{baseUrl}/v1/token
-
Si la autentificación es válida, se obtiene una respuesta con la fecha y hora en formato UTC en la que se ha generado, en la que expira y el propio token.
{ "issuedAt": "2021-04-01T09:09:16.284Z", "expiration": "2021-04-02T09:09:16.284Z", "token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......." }
-
Además, si se realiza una petición con un token expirado se recibe un error HTTP 400 – Bad Request con la respuesta como en el siguiente ejemplo. Se debe solicitar un nuevo token para continuar realizando peticiones a la API.
{ "status": 400, "code": 6, "message": "Expired token received" }
-
Para realizar peticiones a los endpoints de la API se debe adjuntar en las cabeceras de la petición un atributo en la cabecera (Authorization) y su valor será Bearer (el tipo de token obtenido) más el valor del token que has obtenido separado por un espacio. Por ejemplo:
Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJDTW9iaWxpdHkzLjAiLCJzdWIiOiJwcnVlYmEiLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwiaWF0IoxNjE2NDIxMDYyLCJleHAiOjE2MTY0MjQ2NjJ9.N8KimN9_IgtjXX2Wv-rXLKK929mavlkaakxY_NzHVFgN9DWT8bqRVeTaBgL5GbzDfZSPZXDutoVwjdbTEx3FbA
Errores
Como se ha indicado anteriormente, todas las respuestas HTTP que no sean 200 – OK, se pueden considerar inválidas. El formato de la respuesta de error es como el siguiente ejemplo:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
Estos errores tendrán tres categorías principales:
Error de Autentificación
-
HTTP Status: 401 - Unauthorized
Code Message 1 User not found or valid
Error de Cliente
-
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 11 Missing request header 12 Access denied role 13 There is an error in one or more elements of the list
En el caso de obtener un error 3 - Missing required property la respuesta obtenida tendrá un valor en el message que nos indicará los campos que faltan por enviar:
{
"status": 400,
"code": 3,
"message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
}
En el caso de obtener un error 13 - There is an error in one or more elements of the list la respuesta obtenida tendrá un valor en el message que nos indicará los campos donde está el error en forma de array:
{
"status": 400,
"code": 13,
"message": "There is an error in one or more elements of the list",
"errorElements": [
{
"position": 0,
"actionId": "860525f3-d27b-412b-9d79-7f2ef341e663",
"errors": [
"eventTypeId: must be less than or equal to 3",
"hdop: must be greater than or equal to 0"
]
},
{
"position": 1,
"actionId": "017bdb38-6151-4f76-bd9e-34376db36efa",
"errors": [
"speed: must be greater than or equal to 0",
"beaconTypeId: must be less than or equal to 2"
]
}
]
}
Error de Servidor
-
HTTP Status: 500 - Internal Server Error
Code Message 14 Internal error
Swagger
La aplicación dispone de un Swagger autogenerado por el propio código donde se pueden encontrar los diferentes endpoints.
{baseUrl}/swagger-ui/index.html