API ReST

Una API ReST, nota anche come API RESTful, è un'interfaccia di programmazione delle applicazioni (API o API web) conforme ai vincoli dello stile architetturale ReST, che consente l'interazione con servizi web RESTful. Il termine REST, coniato dall'informatico Roy Fielding, è l'acronimo di REpresentational State Transfer.

La documentazione delle API ReST della piattaforma è pubblicamente disponibile in ogni Ente all'indirizzo:

Ad esempio per il comune demo della piattaforma è possibile consultarle alla pagina:

Scaricare le specifiche OpenAPI per Postman

Le specifiche OpenAPI della Stanza del Cittadino sono disponibili direttamente in ogni tenant all'indirizzo:

https://<dominio>/lang/api/doc.json

Ad esempio:

https://servizi.comune.rivoli.to.it/lang/api/doc.json

Scarica il file JSON e importalo in Postman con File → Import, oppure in qualsiasi altro strumento compatibile con le specifiche OpenAPI 3.0.

Autenticazione

Alcune API richiedono un'autenticazione prima di essere chiamate, in questo caso un cittadino o un operatore possono usare le proprie credenziali per ottenere un token di autenticazione come segue:

Scadenza e rinnovo del token

Il token ha una durata di 10 giorni. Alla scadenza le API restituiscono un errore 401 Unauthorized.

Per rinnovarlo, ripeti la chiamata all'endpoint /api/auth con le credenziali dell'operatore API. Non è necessario revocare il token precedente.

Richiesta token di autenticazione

POST https://servizi.comune.bugliano.pi.it/lang/api/auth

Con questa chiamata si riceve un token di autenticazione in formato JWT, che dovrà essere inviato per tutte le successive chiamate che richiedono autenticazione come bearer token nell'header Autorization

Request Body

Name	Type	Description
username*	String	nome utente
password*	String	password

200: OK Se le credenziali sono corrette si riceverà un token di autenticazione

Alcuni esempi di chiamate

Esempio di chiamata da linea di comando con il client Httpie:

echo '{ "username": "my-api-user", "password": "xxxx" }' | \
http post https://servizi.comune.bugliano.pi.it/lang/api/auth

Esempio di chiamata da linea di comando con il client curl:

curl \
--header 'Content-Type: application/json' \
--data $'{\n "username": "my-api-user",\n "password": "xxxx"\n}' \
https://servizi.comune.bugliano.pi.it/lang/api/auth 

Versioni delle API

Le API sono disponibili in due versioni, la "1" e la "2". Le capacità delle API sono le stesse per le due versioni, nella versione 2 c'e' una migliore gestione del formato JSON, quindi si consiglia l'uso della versione più recente.

È possibile specificare la versione delle Api che si vanno ad interrogare, questo è possibile in 2 modi differenti:

• tramite parametro version da passare come parametro delle GET
• tramite parametro X-Accept-Version da specificare nell' header della richiesta

La versione di default è per retrocompatibilità la 1

Dalla versione 2 le chiavi dei valori del campo data delle applications non sono più restituite come un insieme di strighe piatto separato dal punto (.) ma come campo json con le chiavi esplose.

Nota bene: si raccomanda di specificare sempre la versione di API utilizzata, anche se è il default (1), perche' in futuro il default potrebbe cambiare.

Versione 2 dell'API utenti

L'API per il recupero della lista degli utenti è disponibile in due versioni:

• la versione 1 (/lang/api/users) rimane invariata per retrocompatibilità;
• la versione 2 (/lang/api/v2/users) introduce la paginazione dei risultati, necessaria quando il numero di utenti è elevato.

La v2 richiede autenticazione come bearer token nell'header Authorization.

Parametri

Parametro	Tipo	Descrizione
limit	intero	Numero massimo di utenti restituiti
offset	intero	Posizione di partenza nella lista

Per recuperare tutti gli utenti, esegui chiamate successive incrementando offset di limit finché la risposta non restituisce un insieme vuoto.

Esempio:

GET /lang/api/v2/users?limit=10&offset=0
GET /lang/api/v2/users?limit=10&offset=10
GET /lang/api/v2/users?limit=10&offset=20