API-First: progettare il contratto prima del codice

Il problema: l'API come sottoprodotto

Nello sviluppo tradizionale, il backend viene costruito per primo e l'API emerge come effetto collaterale: endpoint creati ad hoc per le esigenze del frontend, formati di risposta inconsistenti, nessuna documentazione, naming senza logica. Il risultato è un'API che funziona ma che nessuno vuole integrare: fragile, imprevedibile e non documentata.

L'approccio API-First inverte la sequenza: prima si progetta l'API come un prodotto, poi si costruisce il backend che la implementa e il frontend che la consuma. L'API non è un effetto collaterale — è il deliverable principale.

Il contratto: OpenAPI come fonte di verità

Il cuore dell'API-First è il contratto: un documento formale che descrive ogni endpoint, ogni parametro, ogni risposta. OpenAPI (ex Swagger) è lo standard: un file YAML/JSON che definisce:

• Endpoint e metodi HTTP (GET /api/v1/articles, POST /api/v1/orders)
• Parametri (path, query, header) con tipo e validazione
• Request body con schema JSON
• Response per ogni status code con schema del payload
• Autenticazione e autorizzazione

Il contratto viene scritto e validato prima di scrivere una riga di codice. Frontend e backend lo usano come riferimento condiviso.

Vantaggi dello sviluppo parallelo

Con il contratto definito, frontend e backend possono lavorare in parallelo:

• Il frontend usa un mock server (Prism, Stoplight) che genera risposte fake basate sullo schema OpenAPI. Può sviluppare e testare l'interfaccia senza aspettare il backend.
• Il backend implementa gli endpoint seguendo il contratto. I test verificano che le risposte siano conformi allo schema.
• Quando entrambi sono pronti, l'integrazione è indolore perché il contratto era condiviso dall'inizio.

API-First in pratica per un freelance PHP

Anche per un progetto one-person, API-First ha vantaggi:

• Chiarezza: il contratto ti forza a pensare all'API prima di scrivere codice. Scopri problemi di design quando costa poco risolverli.
• Documentazione automatica: dal file OpenAPI generi documentazione interattiva (Swagger UI, Redoc) senza sforzo aggiuntivo.
• Validazione automatica: middleware che validano request e response contro lo schema, catturando inconsistenze in development.
• Code generation: da OpenAPI puoi generare client SDK, tipi TypeScript, stub del server.

API come prodotto: design principles

• Consistenza: tutti gli endpoint seguono le stesse convenzioni (naming, paginazione, errori, filtri)
• Versionamento: /api/v1/ permette di evolvere senza rompere i client esistenti
• Error handling uniforme: ogni errore ha lo stesso formato ({ "error": { "code": "...", "message": "..." } })
• HATEOAS: le risposte includono link alle azioni possibili, rendendo l'API auto-descrivente
• Paginazione standard: cursor-based o offset-based, ma sempre uguale in tutti gli endpoint

Quando usare API-First

• Usa API-First quando l'API sarà consumata da client multipli (web, mobile, terze parti)
• Usa API-First quando frontend e backend sono sviluppati da persone o team diversi
• Usa API-First quando l'API è il prodotto stesso (SaaS, piattaforma con integrazioni)
• Non usare API-First per applicazioni server-rendered senza API pubblica: il contratto sarebbe solo burocrazia
• Non usare API-First per prototipi rapidi dove la velocità conta più della formalità

API-First non è solo una pratica tecnica: è un cambio di mentalità. L'API non è un dettaglio implementativo da aggiungere dopo — è il contratto su cui tutto il sistema si costruisce. Quando il contratto è solido, tutto il resto segue naturalmente.