Web API

Introduzione

L’infrastruttura offre una ricca API che consente di eseguire diverse operazioni di supporto nello sviluppo e nell’integrazione del proprio Dominio all’interno di applicazioni proprietarie o in un sistema di terze parti. In questo capitolo vengono spiegati cos’è una API, quali sono gli standard di riferimento seguiti, come avviene l’autenticazione e, nell’ultimo paragrafo, come provare la API direttamente dal sito di riferimento dedicato.

Definizione

Una REST API (nota anche come RESTful API) è una application programming interface (API) conforme ai vincoli dell’architettura REST. REST è l’acronimo di representational state transfer.

Una API è un insieme di definizioni e protocolli per costruire e integrare software applicativo. A volte viene indicata come un contratto tra un fornitore di informazioni (information provider) ed un utilizzatore (information user) - stabilendo il contenuto richiesto dal consumatore (colui che effettua la chiamata) ed il contenuto richiesto dal produttore (colui chi riceve la risposta).

Ogni API HTTP è composta da una richiesta (inviata dal client) e una risposta (inviata dal server).

Per maggiori informazioni su REST API, fare riferimento a https://it.wikipedia.org/wiki/Representational_State_Transfer.

L’anatomia di una richiesta

È importante sapere che una richiesta è composta da quattro parti:

  1. Endpoint

  2. Metodo

  3. Intestazione

  4. Dati (o corpo)

Endpoint

La radice di un endpoint (o indirizzo di base) è il punto di partenza della API a cui si effettua una richiesta. Il punto di partenza delle API è https://ubiquity.asem.it. Il percorso (o path) determina la risorsa che si vuole richiedere e ogni API ha il proprio percorso. Per esempio, il percorso per recuperare l’elenco dei dispositivi è /api/devices mentre il percorso per recuperare l’elenco degli utenti è /api/users.

Metodo

Il metodo è utilizzato per rappresentare l’azione intrapresa sulla risorsa.

Metodo HTTP

Azione CRUD

GET

Leggere (Read)

POST

Creare (Create)

PUT

Aggiornare/Sostituire (Update)

PATCH

Aggiornare/Modificare parzialmente (Update)

DELETE

Cancellare (Delete)

Per maggiori informazioni sui verbi HTTP, fare riferimento a https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.

Intestazione

L’intestazione viene utilizzata per fornire informazioni sia al client sia al server. Può essere utilizzata per vari scopi, come per esempio l’autenticazione, e per fornire informazioni sul contenuto del corpo.

Le intestazioni HTTP sono coppie di tipo proprietà-valore separate da due punti. L’esempio seguente mostra un’intestazione che indica al server di aspettarsi un contenuto di tipo JSON.

Content-Type: application/json

Dati

I dati (a volte chiamati corpo o messaggio) contengono le informazioni che si vogliono inviare al server. Questa opzione viene utilizzata solo con richieste di tipo POST, PUT, PATCH o DELETE.

Il metodo GET è usato in combinazione con i parametri passati direttamente nella stringa di ricerca (specificati alla fine del percorso con una coppia proprietà-valore, preceduta da un punto interrogativo).

La risposta

Una volta che il server ha ricevuto la richiesta da un client, invia una risposta.

La risposta è composta da:

  1. Codice di stato HTTP

  2. Corpo

I codici di stato HTTP sono standardizzati come segue:

  • 200+ significa che la richiesta è riuscita.

  • 300+ significa che la richiesta viene reindirizzata ad un altro URL

  • 400+ significa si è verificato un errore originato dal client

  • 500+ significa si è verificato un errore originato dal server

Il corpo è opzionale e contiene la risposta del server.

Per maggiori informazioni sui codici di stato HTTP, fare riferimento a https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

Autenticazione

Per fornire un accesso sicuro quasi tutte le API REST devono avere una sorta di autenticazione. Una delle intestazioni più comuni è la chiamata Authorization.

Autenticazione vs Autorizzazione

La distinzione tra autenticazione e autorizzazione è importante per capire come funzionano le API RESTful e perché i tentativi di connessione sono accettati o negati:

  • L’autenticazione è la verifica delle credenziali del tentativo connessione. Questo processo consiste nell’inviare le credenziali dal client al server, in chiaro oppure in forma criptata, utilizzando un protocollo di autenticazione.

  • L’autorizzazione è la verifica che il tentativo di connessione sia consentito. L’autorizzazione avviene dopo l’avvenuta autenticazione.

In altre parole: l’autenticazione è l’affermazione che si è, chi si è, mentre l’autorizzazione è chiedere se si ha accesso a una certa risorsa.

Per accedere alle API che richiedono l’autenticazione, è necessario prima di tutto invocare una API di autenticazione per ottenere il Bearer Token in risposta.

Con quel token si possono invocare le altre API specificando il token nell’intestazione HTTP:

'Authorization': 'Bearer <token>'

Per maggiori informazioni su JWT, consultare il sito https://tools.ietf.org/html/rfc7519.

OData v4

Per trattare con le risorse di dominio (Cartelle, Dispositivi, Utenti, Gruppi, etc…), le API sono esposte utilizzando il protocollo OData v4. OData (Open Data Protocol) è stato standardizzato da OASIS e approvato da ISO/IEC Internation Standard e definisce un set di «best practice» per costruire ed utilizzare delle API RESTful.

Sono ammesse le seguenti clausole: $select, $expand, $filter, $top, $orderby e $count.

Per maggiori informazioni su OData v4, consultare il sito https://www.odata.org/documentation.

Informazioni di riferimento per le API

Al seguente URL https://ubiquity.asem.it/api/ viene fornita la documentazione delle API, conforme allo standard OpenAPI 3.0.1.

Nota

In caso di installazione Server Privato UBIQUITY, la documentazione delle API è disponibile all’indirizzo https://#WebAPIEndpoint#/api, dove #WebAPIEndpoint#, è l’endpoint delle Web API e, per esempio, potrebbe essere https://ubiquity.mydomain.com/api. Per maggiori informazioni, vedere il manuale del Server UBIQUITY.

È accessibile tramite lo strumento di interfaccia utente di Swagger. È possibile trovare alcuni esempi di parametri di richiesta, il corpo, ecc… e ogni API può essere provata in autonomia.

Le API che richiedono l’autenticazione sono contrassegnate con un lucchetto sul tag a destra; se si clicca sul lucchetto si può inserire il token JWT per fornire l’autenticazione alla API. Si potrebbe anche inserire l’opzione JWT Bearer Token se si clicca sul pulsante Authorize nella parte superiore destra della pagina; di seguito tutte le richieste API che richiedono autenticazione utilizzeranno quel token.

Per ottenere un token di autenticazione valido è necessario prima di tutto invocare la API di autenticazione fornendo le proprie credenziali e sarà necessario disporre di una licenza UBIQUITY X valida per i servizi di connettività.

In ogni API è possibile trovare un pulsante Try it our per testare la API. Quando lo si preme, si può facilmente cambiare l’esempio del corpo della richiesta con i propri valori, quindi premere il tasto Execute per inviare la richiesta al server.

Per maggiori informazioni su OpenAPI e Swagger, fare riferimento a https://swagger.io/specification/.