Utilizzare le API del sito

Su richiesta dell’Ente, viene messa a disposizione la documentazione per l'utilizzo delle API.

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.

Le piattaforme OpenCity Italia mettono a disposizione, per gli Enti che ne fanno richiesta, una sezione e la documentazione 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 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

Le richieste vengono autenticate tramite Authorization Basic

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).

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

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.

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.