Primii pași

Această secțiune descrie interfața Web API a platformei, implementată ca pachet de date REST API pentru schimbul de date în format json.

Precizări generale

• Formatul de transfer al datelor Interfața Web API este implementată ca pachet de date REST API pentru schimbul de date în format json.
• Procedura de autentificare Autentificarea se bazează pe un token actualizat dinamic, care garantează securitatea datelor primite și previne scurgerea tokenului.
• Formatul variabilelor care conțin data și ora Interfața Web API returnează valorile de tip dată și oră codificate în timp UNIX sau timp POSIX, în formatul UTC: 1613376963. La conversia timpului Unix într-o dată ușor de citit, trebuie indicat fusul orar.
• Paginare Interfața Web API implementează paginarea pentru descărcarea datelor pagină cu pagină. Numărul paginii se transmite în parametrul page="page number" (page=1). Numărul de înregistrări returnate de o interogare se poate stabili prin parametrul per_page, dar cel mult 1.000 de înregistrări.

Adresa URL de bază

Toate exemplele de pe aceste pagini folosesc următoarea adresă URL de bază:

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

Autentificare

Autentificarea se bazează pe un token actualizat dinamic. În practică, procedura arată astfel:

• Autentificarea inițială se face cu o adresă de e-mail și o parolă existente în sistem, iar ca răspuns se primesc un token dinamic și atributele asociate.
• Se formează cererea propriu-zisă pentru obținerea datelor: în anteturile cererii HTTP se adaugă tokenul primit la pasul anterior.
• Cererea se trimite la server. Dacă cererea este formată corect, serverul returnează datele în corpul răspunsului și un token nou în anteturile răspunsului, iar tokenul vechi devine nevalid. Cu tokenul nou se poate repeta pasul anterior și așa mai departe.
• La încheierea lucrului, ultimul token poate fi invalidat înainte de data expirării (SignOut).

Autentificarea inițială folosește adresa de e-mail și parola unui utilizator existent. Pentru aceasta, trimiteți o cerere POST la adresa:

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

Exemplu de cerere în 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

Ca răspuns se primește următorul mesaj:

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

Din acest răspuns ne interesează următoarele anteturi:

Exemplu de cerere cu tokenul din răspunsul 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

Ca răspuns se primește următorul mesaj:

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
}

Pentru a încheia lucrul, puteți fie să folosiți procedura de deconectare (SignOut), fie să salvați anteturile necesare din ultima cerere și să le folosiți data viitoare, dacă durata de valabilitate a tokenului nu a expirat.

Încheierea sesiunii:

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}

Pașii următori

Acum că vă puteți autentifica, explorați resursele principale ale interfeței API: