API Web
L'API Web è un'interfaccia che facilita la comunicazione tra applicazioni software. Consente di sviluppare e integrare il dominio in applicazioni proprietarie o sistemi di terze parti. Le invocazioni API RESTful sono costituite da una richiesta inviata dal client e da una risposta restituita dal server.
Richiesta del client
Una richiesta API RESTful include tre componenti principali:
- Azione HTTP: definisce l'azione da eseguire sulla risorsa endpoint URL.
Azione HTTP GET
Leggere
POST
Creare
PUT
Aggiornare/Sostituire
PATCH
Aggiornamento/modifica parziale
DELETE
Eliminare
- Endpoint URL: consiste in un collegamento URL che rappresenta le risorse a cui si desidera accedere, ad esempio testo, immagini, documenti o dati. L'endpoint radice (o indirizzo di base) è il punto di partenza dell'API da cui si invia la richiesta, mentre il percorso determina la risorsa richiesta. Ogni API ha il proprio percorso (ad esempio, il percorso per recuperare un elenco di dispositivi è: /api/devices, mentre il percorso per recuperare l'elenco di un utente è: /api/utenti). L'endpoint radice dell'API è https://uniqloud.asem.it
- Messaggio del corpo: Include proprietà e valori per creare o aggiornare una determinata risorsa. Un messaggio del corpo può includere intestazioni. Le intestazioni sono coppie proprietà-valore separate da due punti e utilizzate per immettere informazioni sul contenuto del corpo. L'esempio seguente mostra un'intestazione che informa il server di aspettarsi del contenuto JSON:
Tipo di contenuto: application/json
Risposta del server
Una volta che il server ha ricevuto una richiesta http da un client, inviare una risposta composta da due parti:
- Il codice di stato HTTP:
- 200: La richiesta è stata accolta.
- 300: La richiesta viene reindirizzata a un altro URL.
- 400: Si è verificato un errore originato dal client.
- 500: Si è verificato un errore originato dal server.
- Il corpo: Il corpo della risposta viene fornito facoltativamente e il relativo messaggio può variare a seconda della risposta del server.
Autenticazione e autorizzazione
I tentativi di connessione possono essere accettati o negati, a seconda che l'autenticazione o l'autorizzazione non riescano o abbiano esito positivo.
- L'Autenticazione è un processo utilizzato per verificare le credenziali di accesso durante il tentativo di connessione. Le credenziali vengono inviate dal client al server in formato testo normale o crittografato tramite un protocollo di autenticazione.
- L'Autorizzazione è un processo utilizzato per confermare che il tentativo di connessione che si sta tentando di stabilire è consentito. Un'autorizzazione può verificarsi solo dopo un'autenticazione riuscita.
Prima di accedere alle API che richiedono l'autenticazione, richiamare l'API di autenticazione per ottenere il Bearer token in risposta. L''Authorization': Il'Bearer <token>' consente di invocare altre API per specificare il token nell'intestazione http.
Protocollo OData v4
L'OData (Open Data Protocol) è un protocollo aperto che consente la creazione e l'utilizzo di API RESTful, in quanto gestiscono risorse di dominio (dispositivi, utenti, gruppi e così via). OData è conforme agli standard OASIS che definiscono un set di procedure per la creazione e l'utilizzo di API RESTful.
Sono accettate le seguenti clausole: $select, $expand, $filter, $top, $orderby, $count.