|
|
. |
|
|
\ No newline at end of file |
|
|
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}/<mark>v1</mark>/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 of the user registered in the system must be sent as a parameter.
|
|
|
|
|
|
<u>{baseUrl}/v1/token?<mark>cn=prueba</mark></u>
|
|
|
|
|
|
<img src="https://i.loli.net/2021/03/24/jAPwrbJnsd6e7zH.png" title="" alt="2021-03-24-13-25-45-image.png" data-align="center">
|
|
|
|
|
|
- If the authentication is valid, a response is obtained with the date and time when it was generated, when it expires and the token itself.
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"issuedAt": "2021-04-01T09:09:16.284",
|
|
|
"expiration": "2021-04-02T09:09:16.284",
|
|
|
"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
|
|
|
```
|
|
|
|
|
|
<img title="" src="https://i.loli.net/2021/03/24/N759fRtgE2PWn8h.png" alt="2021-03-24-13-21-32-image.png" data-align="center">
|
|
|
|
|
|
## 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 |
|
|
|
|
|
|
#### Server Error
|
|
|
|
|
|
- HTTP Status: **500 - Internal Server Error**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | -------------- |
|
|
|
| 11 | Internal error | |