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
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]"
}
Error de Servidor
-
HTTP Status: 500 - Internal Server Error
Code Message 13 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