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.

Caso d’uso - Pubblicare una notizia e inviarla automaticamente a un sistema esterno

Contesto: Il comune vuole che ogni notizia pubblicata sul sito venga automaticamente inviata a un sistema esterno, ad esempio un'app mobile o un canale di comunicazione, senza intervento manuale del redattore.

Prerequisiti:

• Il modulo API deve essere attivo sull'installazione
• L'utente deve avere i permessi di gestione dei webhook
• Il sistema esterno deve esporre un endpoint pubblico in grado di ricevere richieste HTTP POST

1. Accedere alla sezione webhook

Dal browser, navigare al percorso /webhook/list del sito comunale (es. https://www.comune.bugliano.pi.it/webhook/list).

1. Creare un nuovo webhook

Configurare un nuovo webhook indicando:

• URL endpoint > l'indirizzo del sistema esterno che riceverà la notifica
• Trigger > la pubblicazione di un contenuto di tipo article

1. Pubblicare una notizia

Ogni volta che il redattore pubblica un contenuto di tipo article, il sistema invia automaticamente il payload all'endpoint configurato.

Esempio di payload ricevuto dall'endpoint esterno:

"metadata": {
    "id": 5485,
    "classIdentifier": "article",
    "published": "2026-02-25T00:00:00+01:00",
    "modified": "2026-05-21T16:05:43+02:00",
    "name": { "ita-IT": "Avviso: apertura iscrizioni corsi estivi 2025" },
    "contentUrl": "https://www.comune.bugliano.pi.it/Novita/Notizie/apertura-iscrizioni-corsi-estivi-2025",
    "apiUrl": "https://www.comune.bugliano.pi.it/api/openapi/novita/notizie/6bfd9f145e1d4bc71380e98c5bdad81f#apertura-iscrizioni-corsi-estivi-2025"
  },
  "data": {
    "ita-IT": {
      "title": "Avviso: apertura iscrizioni corsi estivi 2025",
      "content_type": ["Notizia"],
      "abstract": "Azioni e opportunità orientative per la promozione del successo formativo...",
      "published": "2026-02-25T00:00:00+01:00",
      "topics": [ { "name": { "ita-IT": "Politica sociale" } } ],
      "author": [ { "name": { "ita-IT": "Servizio Comunicazione e Informazione" } } ]
    }
  }
}

Il payload ricevuto e la risposta dell'endpoint sono consultabili dall'interfaccia di gestione del webhook.