Prise en main

Cette section décrit la Web API de la plateforme, mise en œuvre sous la forme d’un paquet de données REST-API destiné à l’échange au format json.

Dispositions générales

• Format de transfert des données La Web API est mise en œuvre sous la forme d’un paquet de données REST-API destiné à l’échange au format json.
• Procédure d’authentification L’authentification repose sur un jeton (token) actualisé dynamiquement, qui garantit la sécurité des données reçues et empêche toute fuite du jeton.
• Format des variables contenant la date et l’heure La Web API renvoie les données de type date et heure encodées en UNIX time ou POSIX time, au format UTC: 1613376963. Lors de la conversion de l’Unix time en date lisible, vous devez préciser le fuseau horaire.
• Pagination La Web API propose une fonction de pagination permettant de charger les données page par page. Elle est transmise par le paramètre : page="page number" (page=1). Le nombre d’enregistrements renvoyés par la requête peut être défini par le paramètre per_page, sans toutefois dépasser 1000 enregistrements.

URL de base

Tous les exemples de ces pages utilisent l’URL de base suivante :

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

Authentification

L’authentification repose sur un jeton actualisé dynamiquement. En pratique, cela se déroule ainsi :

• L’authentification initiale s’effectue à l’aide d’une adresse e-mail et d’un mot de passe existants dans le système ; en réponse, un jeton dynamique et les attributs associés sont renvoyés.
• La requête de récupération des données proprement dite est ensuite formée, le jeton obtenu à l’étape précédente étant ajouté aux en-têtes de la requête HTTP.
• La requête est envoyée au serveur. Si elle est correctement formée, le serveur renvoie les données dans le corps de la réponse et un nouveau jeton dans les en-têtes de la réponse, tandis que l’ancien jeton perd sa validité. Avec le nouveau jeton, nous pouvons répéter l’étape précédente, et ainsi de suite.
• Une fois le travail terminé, le dernier jeton peut être invalidé avant sa date d’expiration (SignOut).

L’authentification initiale utilise l’adresse e-mail et le mot de passe d’un utilisateur existant. Pour cela, vous devez envoyer une requête POST à l’adresse suivante :

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

Exemple de requête au format 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 réponse, nous recevrons le message suivant :

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"}}

Dans cette réponse, les en-têtes qui nous intéressent sont les suivants :

Exemple de requête utilisant le jeton de la réponse précédente :

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 réponse, nous recevrons le message suivant :

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
}

Pour terminer le travail, vous pouvez recourir à la procédure SignOut, ou bien conserver les en-têtes nécessaires de la dernière requête et, si la durée de vie du jeton n’a pas expiré, les réutiliser la fois suivante.

Clôture d’une session :

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}

Étapes suivantes

Maintenant que vous savez vous authentifier, explorez les principales ressources de l’API :