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 e 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 e un effetto collaterale — e il deliverable principale.
Il contratto: OpenAPI come fonte di verità
Il cuore dell'API-First e il contratto: un documento formale che descrive ogni endpoint, ogni parametro, ogni risposta. OpenAPI (ex Swagger) e 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 e 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 sara 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 e 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 formalita
API-First non e solo una pratica tecnica: e un cambio di mentalita. L'API non e un dettaglio implementativo da aggiungere dopo — e il contratto su cui tutto il sistema si costruisce. Quando il contratto e solido, tutto il resto segue naturalmente.
