API PDND per Comuni: documentazione, sicurezza e collaudo degli e-service
Una guida operativa per progettare e verificare API ed e-service della Pubblica Amministrazione: fonti dati, OpenAPI, semantica, sicurezza, test e continuità.
In breve: un progetto API per la Pubblica Amministrazione non termina quando un endpoint restituisce dati. Per arrivare a un e-service utilizzabile servono un contratto comprensibile, dati coerenti, misure di sicurezza adeguate, ambienti di prova, pubblicazione sulla PDND e responsabilità operative dopo l’attivazione. Il collaudo deve verificare l’intero percorso, non soltanto una risposta tecnica isolata.
Partire dal servizio e dalla fonte del dato
Prima di progettare risorse e operazioni bisogna chiarire quale servizio amministrativo viene esposto, chi è titolare del dato, quale applicativo lo produce e con quale frequenza viene aggiornato. Nei Comuni la fonte può essere un gestionale verticale, un database storico, un albo online o un middleware che normalizza informazioni provenienti da più sistemi.
La prima attività consiste quindi nel mappare campi, identificativi, stati, date, allegati, relazioni e casi anomali. Se questa analisi viene saltata, l’API rischia di descrivere bene dati che nel sistema sorgente hanno significati diversi o non sono sufficientemente affidabili. Il contratto tecnico deve riflettere il processo reale, senza inventare informazioni che la fonte non possiede.
Il descrittore OpenAPI è parte del prodotto
Per le API REST, PA digitale 2026 indica la documentazione YAML o JSON in formato OpenAPI 3 e i riferimenti alla semantica utilizzata; per le API SOAP viene usato WSDL. La stessa risorsa segnala un validatore sintattico e raccomanda di allegare indicazioni su configurazioni e ulteriori livelli di sicurezza eventualmente necessari. Fonte: PA digitale 2026 — documentazione tecnica a corredo delle API.
OpenAPI non dovrebbe essere scritto alla fine per rendicontare un lavoro già concluso. Se usato durante la progettazione, permette a ente, fornitore e integratori di concordare prima dello sviluppo:
- risorse, operazioni e percorsi disponibili;
- parametri obbligatori, filtri, paginazione e ordinamento;
- struttura delle risposte positive e degli errori;
- tipi, formati, valori ammessi ed esempi non sensibili;
- schemi di autenticazione e condizioni di accesso;
- versione dell’interfaccia e regole per modificarla.
Un descrittore formalmente valido può comunque essere ambiguo. Nomi dei campi, vocabolari, codici e significato degli stati devono essere spiegati pensando a chi consumerà il servizio senza conoscere il gestionale originario.
Semantica e minimizzazione
L’interoperabilità non coincide con la semplice esportazione di una tabella. Campi apparentemente uguali possono rappresentare concetti differenti; campi tecnici interni possono non essere utili al fruitore; dati personali o informazioni riservate non devono essere esposti per comodità. Il modello deve contenere ciò che serve al servizio autorizzato e rendere esplicita la provenienza delle informazioni.
Una scheda semantica utile associa a ogni proprietà descrizione, obbligatorietà, formato, vocabolario, fonte e regole di valorizzazione. Le assenze vanno distinte dai valori zero o dagli stati “non applicabile”. Anche gli errori devono essere coerenti: un fruitore deve poter distinguere una richiesta malformata, un’autorizzazione insufficiente, una risorsa inesistente e un problema temporaneo.
Sicurezza: identità, autorizzazione e tracciabilità
Le Linee guida sull’interoperabilità tecnica descrivono standard, ruoli e pattern del Modello di Interoperabilità per scambi affidabili e coerenti. L’implementazione concreta dipende dal servizio, ma il progetto deve almeno chiarire identità del fruitore, autorizzazioni, gestione delle credenziali, trasporto cifrato e registrazione degli eventi.
Autenticazione
Verificare chi effettua la richiesta e con quali credenziali, evitando segreti condivisi nei file o nelle email.
Autorizzazione
Concedere soltanto operazioni e dati coerenti con l’accordo di fruizione e con il servizio richiesto.
Log tecnici
Registrare esito, tempi e identificativi di correlazione senza trasformare i log in copie indiscriminate dei dati scambiati.
Gestione incidenti
Definire contatti, allarmi, revoca delle credenziali e azioni da seguire quando il servizio non risponde correttamente.
Dallo sviluppo all’e-service attivo
La verifica PNRR della Misura 1.3.1 non si limita alla presenza di codice sul server. PA digitale 2026 indica che gli e-service richiesti devono risultare attivi nel Catalogo API della PDND. I controlli automatici considerano codice IPA dell’ente, nome, hash e data della prima pubblicazione dell’e-service. Fonte: PA digitale 2026 — verifiche di conformità tecnica.
Conviene perciò gestire come un’unica sequenza descrittore, implementazione, configurazione, pubblicazione, attivazione e prova di fruizione. Ambiente di test e ambiente di produzione devono essere distinguibili. URL, certificati, credenziali e dipendenze non devono essere scoperti soltanto durante il collaudo finale.
Una matrice di collaudo leggibile
Il piano di test dovrebbe collegare ogni requisito a una prova, un risultato atteso e un’evidenza conservabile. Le verifiche minime comprendono:
- Contratto: validazione del descrittore e coerenza tra documentazione e comportamento reale.
- Dati: casi ordinari, assenze, valori limite, caratteri speciali, date e paginazione.
- Errori: richieste incomplete, parametri errati, risorse inesistenti e indisponibilità della fonte.
- Sicurezza: credenziali mancanti, scadute o non autorizzate e controllo delle operazioni consentite.
- Prestazioni: tempi compatibili con l’uso previsto e comportamento sotto carico concordato.
- Continuità: log, monitoraggio, backup delle configurazioni e procedura di ripristino.
- PDND: pubblicazione e attivazione dell’e-service con elementi coerenti con il progetto.
Le prove automatiche sono utili, ma non sostituiscono il controllo dei significati e dei casi amministrativi. Una risposta HTTP 200 può contenere dati incompleti; un errore correttamente gestito può invece dimostrare che il sistema protegge il servizio.
Dopo il collaudo: manutenzione e responsabilità
Gestionali e normative evolvono. Un campo può cambiare formato, una dipendenza può richiedere aggiornamenti, una credenziale può scadere. Per evitare che l’e-service smetta di funzionare dopo il progetto servono referente dell’ente, referente tecnico, monitoraggio, finestre di manutenzione, gestione delle versioni e regole per comunicare modifiche ai fruitori.
È utile consegnare inventario degli ambienti, dipendenze, configurazioni, procedure operative e contatti, separando sempre documentazione condivisibile e segreti. Il passaggio di consegne deve permettere all’ente di comprendere cosa è attivo e come chiedere assistenza.
Il caso API Albo Pretorio
DLM Design ha sviluppato per i Comuni di Venetico, Limina, Gioiosa Marea e Aidone un servizio middleware per l’interoperabilità dell’Albo Pretorio nell’ambito della Misura 1.3.1. Il progetto comprende API REST, descrizione Swagger/OpenAPI, OAuth2 e collegamento con i sistemi comunali, senza esporre nella scheda pubblica configurazioni o dati riservati.