Primeros pasos

Esta sección describe la Web API de la plataforma, implementada como REST-API con intercambio de datos en formato json.

Aspectos generales

• Formato de transferencia de datos La Web API está implementada como REST-API con intercambio de datos en formato json.
• Procedimiento de autenticación La autenticación se basa en un token que se actualiza dinámicamente, lo que garantiza la seguridad de los datos recibidos e impide la filtración del token.
• Formato de las variables que contienen fecha y hora La Web API devuelve los datos de tipo fecha y hora codificados en UNIX time o POSIX time, con el formato UTC: 1613376963. Para convertir el Unix time en una fecha legible es necesario indicar la zona horaria.
• Paginación La Web API implementa la paginación para cargar los datos página a página. Se transmite mediante el parámetro: page="page number" (page=1). El número de registros que devuelve la consulta puede indicarse con el parámetro per_page, pero nunca más de 1000 registros.

URL base

Todos los ejemplos de estas páginas utilizan la siguiente URL base:

https://api.vadsro.eu/api/v1

Autenticación

La autenticación se basa en un token que se actualiza dinámicamente. En la práctica, funciona así:

• La autenticación primaria se realiza con un correo electrónico y una contraseña existentes en el sistema; en la respuesta se reciben un token dinámico y los atributos asociados.
• Se construye la solicitud de datos propiamente dicha, añadiendo a los encabezados de la solicitud HTTP el token recibido en el paso anterior.
• Se envía la solicitud al servidor. Si la solicitud está bien formada, el servidor devuelve los datos en el cuerpo de la respuesta y un token nuevo en los encabezados de la respuesta, mientras que el token anterior deja de ser válido. Con el token nuevo podemos repetir el paso anterior, y así sucesivamente.
• Al terminar el trabajo, el último token puede invalidarse antes de su fecha de caducidad (SignOut).

La autenticación inicial utiliza el correo electrónico y la contraseña de un usuario existente. Para ello hay que enviar una solicitud POST a la dirección:

https://api.vadsro.eu/api/v1/auth/sign_in

Ejemplo de solicitud en formato Curl:

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api-user@example.com","password":"Str0ngPas$"}'\
     https://api.vadsro.eu/api/v1/auth/sign_in

En respuesta recibiremos el siguiente mensaje:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-1
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615227012
uid: api-user@example.com
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api-user@example.com","provider":"email","uid":"api-user@example.com","name":"API user"}}

En esta respuesta nos interesan los siguientes encabezados:

Ejemplo de solicitud que utiliza el token de la respuesta anterior:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-1" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://api.vadsro.eu/api/v1/stations

En respuesta recibiremos el siguiente mensaje:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-2
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615311367
uid: api-user@example.com
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"860000000000001","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}

Para terminar el trabajo puedes utilizar el procedimiento SignOut, o bien guardar los encabezados necesarios de la última solicitud y reutilizarlos la próxima vez, si el tiempo de vida del token no ha expirado.

Cierre de una sesión:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-2" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request DELETE \
 https://api.vadsro.eu/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}

Próximos pasos

Ahora que ya sabes autenticarte, explora los recursos principales de la API: