> 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/sito-web/moduli-integrativi-della-piattaforma/utilizzare-le-api-del-sito.md). # Utilizzare le API del sito {% hint style="info" %} Le API (Application Programming Interface, ovvero Interfaccia di Programmazione delle Applicazioni) sono un insieme di regole, protocolli e strumenti che consentono a diverse applicazioni software di comunicare tra loro. Le API funzionano come un intermediario che consente alle applicazioni di scambiarsi dati e funzioni in modo semplice e sicuro. {% endhint %} Le piattaforme OpenCity Italia mettono a disposizione, per gli Enti che ne fanno richiesta, una sezione e la [documentazione](#documentazione-api) dedicata all'utilizzo delle API. Le API a disposizione rispettano quella che è la struttura del sito web: pertanto, il loro uso da parte dei redattori è regolamentato dagli [permessi di gestione dei contenuti](/sito-web/la-piattaforma/accedere-alla-piattaforma/attribuzione-dei-permessi.md) amministrati nella sezione “Gestione accessi redazione”. L'utilizzo delle API permette di effettuare azioni aggiuntive, come ad esempio disporre dei Dataset anche in formato JSON (basati su standard di interoperabilità di AgID) oppure automatizzare la pubblicazione di documenti sul sito web (es. Documenti di Albo pretorio), evitando quindi di crearli manualmente all’interno. ## Documentazione API {% hint style="warning" %} Le richieste vengono autenticate tramite Authorization Basic {% endhint %} Una volta attivato il modulo, gli utenti abilitati potranno accedere alla documentazione API presente sulla piattaforma, raggiungibile dal percorso "**/openapi/doc**" del proprio sito (es. ). All'interno della documentazione, sono elencate le classi di contenuto che possono essere gestite tramite API.
Cliccando su una di queste, il redattore visualizza le chiamate API disponibili per la classe di contenuto.
## I webhook {% hint style="info" %} Una volta configurato, è possibile eseguire un test del webhook per assicurarsi che la configurazione sia corretta e che il server risponda. Gli endpoint possono essere analizzati e monitorati tramite [Request Inspector.](https://requestinspector.com/) {% endhint %} Con l'attivazione del modulo API, all'Ente viene messa a disposizione una sezione del sito dedicata alla configurazione dei webhook, raggiungibile dal percorso "/webhook/list" del sito web (es. ) I webhook permettono di collegarsi a un trigger: ogni volta che viene pubblicato un contenuto, un *endpoint* configurato viene contattato automaticamente. * **Attivazione e gestione**: ogni webhook può essere abilitato o disabilitato in qualsiasi momento. * **Retry automatico**: in caso di errore, è previsto un meccanismo di ritentativi con scadenze esponenziali. Dopo 11 tentativi falliti, il processo viene interrotto. * **Gestione degli errori**: se la risposta dell’endpoint contiene valori non validi, vengono mostrati gli **header** e il **body** dell’errore riscontrato. * **Payload e risposte**: a ogni chiamata viene generato un **payload**, consultabile all’interno dell’interfaccia. Anche la risposta dell’endpoint viene registrata e resa disponibile (response-show response). ### Esempi d’uso * Pubblicare un contenuto sul sito che, tramite webhook, viene automaticamente replicato su altre piattaforme. * Integrare il sistema con software esterni: un webhook può essere collegato potenzialmente a qualsiasi applicativo. * A livello di codice è possibile definire ulteriori *trigger* personalizzati. --- # 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/sito-web/moduli-integrativi-della-piattaforma/utilizzare-le-api-del-sito.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.