# 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](https://docs.opencityitalia.it/manuale-opencity-italia-sito-web-istituzionale-v3/la-piattaforma/accedere-alla-piattaforma/attribuzione-dei-permessi) 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. <https://www.comune.bugliano.pi.it/openapi/doc>).&#x20;

All'interno della documentazione, sono elencate le classi di contenuto che possono essere gestite tramite API.

<figure><img src="https://3823931934-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfYDGLbEkTaK5gywjDOEN%2Fuploads%2Fhy3JkKLPDQbb2G2vLRI2%2Fimage.png?alt=media&#x26;token=d799cc28-6fc8-46d4-b8bf-f9534c1f11a6" alt=""><figcaption></figcaption></figure>

Cliccando su una di queste, il redattore visualizza le chiamate API disponibili per la classe di contenuto.

<figure><img src="https://3823931934-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfYDGLbEkTaK5gywjDOEN%2Fuploads%2Fig1ZwjHBuyzW0OBI6W9e%2Fimage.png?alt=media&#x26;token=df64cd5d-e5f5-4ed5-b92b-f3920c446fbb" alt=""><figcaption></figcaption></figure>

## 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. <https://www.comune.bugliano.pi.it/webhook/list>)

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.