Guida introduttiva

Questa sezione descrive la Web API della piattaforma, implementata come REST-API con scambio di dati in formato json.

Principi generali

• Formato di trasferimento dei dati La Web API è implementata come REST-API con scambio di dati in formato json.
• Procedura di autenticazione L’autenticazione si basa su un token aggiornato dinamicamente, che garantisce la sicurezza dei dati ricevuti e impedisce la fuga del token.
• Formato delle variabili contenenti data e ora La Web API restituisce i dati di tipo data e ora nella codifica UNIX time o POSIX time, nel formato UTC: 1613376963. Per convertire il valore Unix time in una data leggibile è necessario indicare il fuso orario.
• Paginazione La Web API implementa la paginazione per il caricamento dei dati pagina per pagina. Si trasmette tramite il parametro: page="page number" (page=1). Il numero di record restituiti dalla richiesta può essere indicato con il parametro per_page, ma non oltre 1000 record.

URL di base

Tutti gli esempi di queste pagine utilizzano il seguente URL di base:

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

Autenticazione

L’autenticazione si basa su un token aggiornato dinamicamente. In pratica funziona così:

• L’autenticazione primaria viene eseguita con un indirizzo e-mail e una password esistenti nel sistema; in risposta si ricevono un token dinamico e i relativi attributi.
• Si compone la richiesta effettiva per ottenere i dati, aggiungendo alle intestazioni della richiesta HTTP il token ricevuto al passaggio precedente.
• Si invia la richiesta al server. Se la richiesta è composta correttamente, il server restituisce i dati nel corpo della risposta e un nuovo token nelle intestazioni della risposta, mentre il token precedente perde validità. Con il nuovo token possiamo ripetere il passaggio precedente e così via.
• Al termine delle operazioni, l’ultimo token può essere invalidato prima della sua data di scadenza (SignOut).

L’autenticazione iniziale utilizza l’indirizzo e-mail e la password di un utente esistente. A tal fine è necessario inviare una richiesta POST all’indirizzo:

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

Esempio di richiesta in 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

In risposta riceveremo il seguente messaggio:

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

In questa risposta ci interessano le seguenti intestazioni:

Esempio di richiesta che utilizza il token della risposta precedente:

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

In risposta riceveremo il seguente messaggio:

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
}

Per concludere le operazioni è possibile utilizzare la procedura SignOut, oppure salvare le intestazioni necessarie dell’ultima richiesta e riutilizzarle la volta successiva, se il token non è ancora scaduto.

Chiusura di una sessione:

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}

Passaggi successivi

Ora che sai come autenticarti, esplora le risorse principali dell’API: