Začínáme

Tato sekce popisuje Web API platformy, které je implementováno jako datový balík REST-API pro výměnu dat ve formátu json.

Obecné principy

Formát přenosu dat Web API je implementováno jako datový balík REST-API pro výměnu dat ve formátu json.
Postup autentizace Autentizace je založena na dynamicky obnovovaném tokenu, který zaručuje bezpečnost přijímaných dat a zabraňuje úniku tokenu.
Formát proměnných obsahujících datum a čas Web API vrací data typu datum a čas v kódování UNIX time nebo POSIX time ve formátu UTC: 1613376963. Při převodu Unix time na čitelné datum je nutné uvést časové pásmo.
Stránkování Web API nabízí stránkování pro postupné načítání dat po stránkách. Předává se parametrem: page="page number" (page=1). Počet záznamů vrácených v dotazu lze určit parametrem per_page, nejvýše však 1000 záznamů.

Základní URL

Všechny příklady na těchto stránkách používají následující základní URL:

bash

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

Autentizace

Autentizace je založena na dynamicky obnovovaném tokenu. V praxi vypadá takto:

Primární autentizace se provádí pomocí e-mailu a hesla existujících v systému; v odpovědi se vrací dynamický token a související atributy.
Sestavení cílového požadavku na získání dat, do jehož hlaviček HTTP se přidá token obdržený v předchozím kroku.
Odeslání požadavku na server. Je-li požadavek sestaven správně, vrátí server data v těle odpovědi a nový token v hlavičkách odpovědi, přičemž starý token pozbývá platnosti. S novým tokenem můžeme zopakovat předchozí krok a tak dále.
Po dokončení práce lze poslední token zneplatnit ještě před vypršením jeho platnosti (SignOut).

Počáteční autentizace používá e-mail a heslo existujícího uživatele. K tomu je třeba odeslat požadavek POST na adresu:

bash

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

Příklad požadavku ve formátu 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 odpovědi obdržíme následující zprá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 této odpovědi nás zajímají následující hlavičky:

Hlavička	Popis
`access_token`	Hodnota této hlavičky slouží jako heslo pro každý požadavek. S každým požadavkem se hodnota mění.
`client`	Tato hlavička je jedinečná pro aktuální připojení. Umožňuje více současně aktivních relací.
`expiry`	Čas, kdy platnost tohoto tokenu vyprší. Výchozí hodnota jsou 2 týdny od okamžiku jeho obdržení. Nebo SignOut pro předčasné ukončení platnosti. Pro následující požadavek není potřeba.
`uid`	Jedinečná hodnota identifikující uživatele. V našem případě e-mail.
`token-type`	Typ použitého tokenu.

Příklad požadavku s použitím tokenu z předchozí odpovědi:

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 odpovědi obdržíme následující zprá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
}

Práci lze ukončit procedurou SignOut, případně si uložit potřebné hlavičky z posledního požadavku a použít je příště, pokud doba platnosti tokenu dosud nevypršela.

Ukončení relace:

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}