API contract-first: progettare il contratto prima del codice

API contract-first significa definire il comportamento di un servizio prima di svilupparne l’implementazione. Il contratto diventa il riferimento condiviso tra frontend, backend, sistemi esterni, test e stakeholder: chiarisce quali risorse esistono, quali dati entrano ed escono, come vengono segnalati gli errori e quali regole di sicurezza devono essere rispettate.

Non è burocrazia tecnica. È un modo per ridurre ambiguità, rilavorazioni e integrazioni fragili, soprattutto quando più team lavorano in parallelo o quando un’API deve rimanere stabile nel tempo.

Che cos’è l’approccio API contract-first

Nel modello code-first l’API emerge dal codice già scritto e la documentazione viene generata in seguito. Nel modello contract-first il documento OpenAPI precede il codice: viene discusso, validato e usato come base per mock, test, client e server.

La OpenAPI Specification 3.1.1, pubblicata nell’ottobre 2024, descrive una interfaccia standard e indipendente dal linguaggio per le API HTTP. Un documento OpenAPI permette a persone e strumenti di comprendere il servizio senza accedere al sorgente; può inoltre alimentare documentazione, generatori di client e server, validatori e test automatici.

Il vantaggio operativo è semplice: si concorda prima ciò che il sistema deve promettere, poi ciascun gruppo implementa la propria parte contro la stessa promessa.

Prerequisiti: il contratto nasce dal dominio, non dallo YAML

Prima di aprire un editor occorre definire il problema. Qual è la risorsa principale? Chi può leggerla o modificarla? Quali stati attraversa? Quali dati sono obbligatori? Una buona API non è una raccolta casuale di endpoint: rappresenta processi e responsabilità del dominio.

Per una prima sessione di progettazione servono almeno:

• un owner funzionale che conosca il processo;
• un referente frontend o consumer dell’API;
• un referente backend e uno per sicurezza e dati;
• tre o quattro casi d’uso reali, inclusi quelli di errore;
• criteri condivisi per compatibilità, versionamento e dismissione.

Anche l’esperienza italiana dell’interoperabilità va in questa direzione: l’ecosistema descritto da Developers Italia collega Catalogo API, PDND, modelli semantici e validazione formale. Il principio utile anche alle imprese è che un’interfaccia comprensibile e verificabile vale più di una documentazione ricostruita a posteriori.

Metodo passo passo per una specifica minima

1. Definire risorse, operazioni e confini

Partire dai nomi del dominio: clienti, ordini, prenotazioni, fatture. Gli endpoint dovrebbero esprimere risorse e relazioni, mentre i verbi HTTP indicano l’operazione. Per ogni operazione vanno esplicitati scopo, autorizzazioni, parametri, filtri, ordinamento e comportamento idempotente.

Un contratto minimo deve già distinguere tra lettura di una collezione, dettaglio di una risorsa, creazione e aggiornamento. Va inoltre chiarito cosa accade quando due richieste modificano lo stesso dato.

2. Modellare richieste e risposte con esempi

Gli schemi devono indicare tipo, formato, obbligatorietà, vincoli e valori ammessi. Gli esempi non sostituiscono lo schema, ma rendono immediatamente visibili convenzioni e casi limite. Inserire almeno un esempio valido e uno problematico per ogni operazione critica.

openapi: 3.1.0
paths:
  /bookings/{bookingId}:
    get:
      responses:
        '200':
          description: Prenotazione trovata
        '404':
          description: Prenotazione non disponibile

La specifica non deve descrivere solo il caso felice. Se errori e assenze non sono progettati, ogni team finirà per interpretarli in modo diverso.

3. Adottare un modello di errore coerente

Ogni errore dovrebbe contenere un codice stabile leggibile dalle macchine, un messaggio comprensibile, un identificativo di correlazione e, quando opportuno, dettagli sui campi non validi. Il codice HTTP da solo non basta: due errori 400 possono richiedere azioni completamente diverse.

È utile separare gli errori di validazione, autenticazione, autorizzazione, conflitto e indisponibilità temporanea. Non bisogna invece esporre stack trace, query, percorsi interni o altri dettagli che facilitino un attacco.

4. Progettare autenticazione e autorizzazione

Il contratto OpenAPI permette di dichiarare schemi come OAuth 2.0, API key o mutual TLS. La scelta dipende da scenario, sensibilità dei dati e identità dei consumer. Ma autenticare una richiesta non significa autorizzarla: il sistema deve verificare anche quali oggetti e quali azioni sono consentiti a quello specifico soggetto.

L’OWASP API Security Top 10 2023 richiama rischi come autorizzazioni errate sugli oggetti, autenticazione compromessa, consumo incontrollato di risorse e inventario incompleto. Questi controlli devono entrare nel contratto e nei test, non essere aggiunti alla fine.

5. Stabilire versionamento e compatibilità

La versione non risolve ogni rottura. Prima di creare una nuova major release, bisogna distinguere tra modifiche compatibili e incompatibili. Aggiungere un campo opzionale è generalmente meno rischioso che rinominare una proprietà, rimuovere un valore enumerato o cambiare il significato di uno status.

Definire una policy: durata del supporto, preavviso di deprecazione, canale di comunicazione e metriche d’uso. Un inventario aggiornato evita che endpoint dimenticati restino attivi senza manutenzione.

Dal contratto al lavoro parallelo

Una volta approvata la specifica, il frontend può usare un mock server, il backend può generare uno scheletro coerente, il QA può preparare test di conformità e il team di sicurezza può verificare requisiti e scenari abusivi. La pipeline dovrebbe bloccare modifiche incompatibili non approvate attraverso linting, validazione dello schema e confronto tra versioni.

Il contratto non va congelato: cambia attraverso una revisione tracciata. La regola è che il documento e l’implementazione devono evolvere insieme. Una pull request che modifica il comportamento dell’API dovrebbe aggiornare anche specifica, esempi e test.

Checklist finale prima di sviluppare

• Risorse, operazioni e casi d’uso sono comprensibili anche al consumer?
• Richieste e risposte includono vincoli ed esempi?
• Gli errori hanno formato uniforme e codici stabili?
• Autenticazione, autorizzazione e limiti di consumo sono dichiarati?
• Esistono regole per compatibilità, deprecazione e versionamento?
• La specifica è validata automaticamente e alimenta mock e test?
• È chiaro chi approva e mantiene il contratto?

Per una PMI il risultato non è soltanto un’API più elegante: è una riduzione del rischio operativo quando sito, app, gestionale, CRM e partner devono scambiarsi dati. Nella mia attività di sviluppo web e integrazione tratto il contratto come un prodotto condiviso, con requisiti, sicurezza e criteri di evoluzione espliciti.

Devi progettare o mettere in sicurezza un’integrazione? Analizziamo architettura, sicurezza e qualità del progetto digitale.