Začíname

Táto sekcia popisuje Web API platformy, ktoré je implementované ako dátový balík REST-API na výmenu údajov vo formáte json.

Všeobecné informácie

Formát prenosu údajov Web API je implementované ako dátový balík REST-API na výmenu údajov vo formáte json.
Postup autentifikácie Autentifikácia je založená na dynamicky aktualizovanom tokene, ktorý zaručuje bezpečnosť prijímaných údajov a zabraňuje úniku tokenu.
Formát premenných obsahujúcich dátum a čas Web API vracia údaje typu dátum a čas v kódovaní UNIX time alebo POSIX time vo formáte UTC: 1613376963. Pri prevode Unix time na čitateľný dátum je potrebné uviesť časové pásmo.
Stránkovanie (pagination) Web API poskytuje stránkovanie na postupné načítavanie údajov po stránkach. Odovzdáva sa parametrom: page="page number" (page=1). Počet záznamov vrátených v požiadavke možno určiť parametrom per_page, najviac však 1000 záznamov.

Základná URL

Všetky príklady na týchto stránkach používajú túto základnú URL:

bash

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

Autentifikácia

Autentifikácia je založená na dynamicky aktualizovanom tokene. V praxi to vyzerá takto:

Prvotná autentifikácia sa vykoná pomocou e-mailu a hesla, ktoré existujú v systéme; v odpovedi sa vrátia dynamický token a súvisiace atribúty.
Zostavenie cieľovej požiadavky na získanie údajov, pričom token prijatý v predchádzajúcom kroku sa pridá do hlavičiek HTTP požiadavky.
Odoslanie požiadavky na server. Ak je požiadavka zostavená správne, server vráti údaje v tele odpovede a nový token v hlavičkách odpovede, pričom starý token stratí platnosť. S novým tokenom môžeme zopakovať predchádzajúci krok a tak ďalej.
Po dokončení práce možno posledný token zneplatniť ešte pred uplynutím jeho platnosti (SignOut).

Prvotná autentifikácia používa e-mail a heslo existujúceho používateľa. Na tento účel je potrebné odoslať požiadavku POST na adresu:

bash

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

Príklad požiadavky vo formáte Curl:

bash

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

V odpovedi dostaneme nasledujúcu správu:

bash

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

V tejto odpovedi nás zaujímajú nasledujúce hlavičky:

Hlavička	Popis
`access_token`	Hodnota tejto hlavičky sa používa ako heslo pri každej požiadavke. Hodnota sa mení s každou požiadavkou.
`client`	Táto hlavička je jedinečná pre aktuálne spojenie. Umožňuje viacero súčasne aktívnych relácií.
`expiry`	Čas, keď platnosť tohto tokenu uplynie. Predvolene 2 týždne od okamihu jeho prijatia. Prípadne SignOut na predčasné zneplatnenie. Pre nasledujúcu požiadavku nie je potrebná.
`uid`	Jedinečná hodnota identifikujúca používateľa. V našom prípade e-mail.
`token-type`	Typ použitého tokenu.

Príklad požiadavky, ktorá používa token z predchádzajúcej odpovede:

bash

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

V odpovedi dostaneme nasledujúcu správu:

bash

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
}

Na ukončenie práce môžete použiť procedúru SignOut, prípadne uložiť potrebné hlavičky z poslednej požiadavky a použiť ich nabudúce, ak platnosť tokenu ešte neuplynula.

Ukončenie relácie:

bash

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}