API ReST
Le API consentono di leggere e modificare informazioni sulla piattaforma in modo programmatico.
Last updated
Le API consentono di leggere e modificare informazioni sulla piattaforma in modo programmatico.
Last updated
Documentazione Opencity Italia
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:
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:
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
Name | Type | Description |
---|---|---|
username* | String | nome utente |
password* | String | password |
Alcuni esempi di chiamate
Esempio di chiamata da linea di comando con il client Httpie:
Esempio di chiamata da linea di comando con il client curl:
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.