> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazioni-con-il-flusso-delle-pratiche/api-rest.md). # 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:///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 | {% tabs %} {% tab title="200: OK Se le credenziali sono corrette si riceverà un token di autenticazione" %} {% endtab %} {% endtabs %} Alcuni esempi di chiamate Esempio di chiamata da linea di comando con il client [Httpie](https://httpie.io/): ``` 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 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazioni-con-il-flusso-delle-pratiche/api-rest.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.