Il contesto: un app mobile con un backend fragile
Una startup nel settore delivery mi ha contattato come sviluppatore PHP freelance con un problema urgente: la loro app mobile funzionava, aveva circa 2.000 utenti attivi, ma il backend stava collassando. Il codice server era un insieme di script PHP senza struttura: file singoli per ogni endpoint, nessuna separazione tra logica e accesso ai dati, nessuna autenticazione sicura e nessun rate limiting. Le risposte JSON avevano formati diversi a seconda dell endpoint — a volte un array, a volte un oggetto, a volte una stringa.
Con la crescita degli utenti il sistema era diventato instabile: timeout frequenti, risposte lente (media 380ms), crash del database durante i picchi di traffico all ora di pranzo e nessun modo di capire cosa stesse succedendo perche non c era logging. Il team mobile passava piu tempo a gestire i workaround per il backend rotto che a sviluppare nuove funzionalita.
Perche riscrivere e non rattoppare
Ho valutato due opzioni. La prima era intervenire sul codice esistente aggiungendo autenticazione, validazione e cache. Il problema: il codice era talmente destrutturato che ogni modifica rischiava di rompere endpoint che funzionavano. La seconda opzione era una riscrittura completa del backend con architettura REST pulita, mantenendo la compatibilita con l app mobile esistente. Il costo della riscrittura era superiore, ma il risultato sarebbe stato un sistema su cui poter costruire per i prossimi 2-3 anni senza debito tecnico.
La startup ha scelto la riscrittura. Ho concordato un piano di migrazione graduale: i nuovi endpoint sarebbero stati sviluppati in parallelo a quelli vecchi, e l app mobile sarebbe stata aggiornata per puntare ai nuovi endpoint uno alla volta, senza big bang.
Architettura dell API REST
Struttura del progetto
Ho progettato il backend con architettura MVC adattata per API: controller dedicati per ogni risorsa (utenti, ordini, prodotti, notifiche), service layer per la logica di business, repository per l accesso ai dati e middleware per le funzionalita trasversali. Ogni componente ha una responsabilita singola e chiara.
Routing RESTful con versioning
Tutti gli endpoint sono sotto il prefisso /api/v1/. Questo permette di rilasciare una v2 in futuro senza rompere i client esistenti. Le risorse seguono le convenzioni REST standard: GET /api/v1/orders per la lista, GET /api/v1/orders/{id} per il dettaglio, POST /api/v1/orders per la creazione. Nessuna eccezione, nessun endpoint "creativo".
Autenticazione e sicurezza
Ho implementato autenticazione JWT con access token (scadenza 15 minuti) e refresh token (scadenza 30 giorni). L access token breve limita la finestra di esposizione in caso di compromissione. Il refresh token e memorizzato nel database con hash, revocabile in qualsiasi momento. Ogni richiesta autenticata passa attraverso un middleware che verifica il token, estrae l utente e lo inietta nel controller.
- Rate limiting: 100 richieste/minuto per utente autenticato, 20/minuto per IP non autenticato. Superato il limite, il server risponde con HTTP 429 e header Retry-After
- Validazione input: ogni endpoint ha regole di validazione dichiarative. Input non valido produce HTTP 422 con dettaglio degli errori in formato consistente
- CORS configurato per accettare solo le origini autorizzate
- SQL injection prevenuta al 100% con prepared statements via PDO — nessuna query costruita con concatenazione di stringhe
Cache e performance
Le risposte GET vengono cachate con chiave basata su endpoint + parametri + utente. La cache viene invalidata automaticamente su ogni operazione di scrittura (POST, PUT, DELETE) che tocca la stessa risorsa. Ho implementato anche un meccanismo di ETag per le risposte: se il client invia l header If-None-Match con l ETag precedente e i dati non sono cambiati, il server risponde con HTTP 304 senza body, risparmiando banda.
Logging e monitoraggio
Ogni richiesta viene loggata con: timestamp, endpoint, metodo HTTP, tempo di risposta, codice HTTP, utente (se autenticato) e IP. I log sono strutturati in formato JSON, parsabili automaticamente. Ho configurato alert automatici per: tempo di risposta medio sopra i 200ms, tasso di errori 5xx sopra l 1%, tentativi di autenticazione falliti sopra i 10 per IP in 5 minuti.
Il processo di migrazione
La migrazione e durata 3 settimane. La prima settimana ho sviluppato il core dell API (routing, autenticazione, middleware, formato risposte). La seconda settimana ho implementato tutti gli endpoint, partendo dai piu critici (login, lista ordini, creazione ordine). La terza settimana e stata dedicata ai test, alla documentazione degli endpoint e alla migrazione graduale dell app mobile.
Ho scritto una documentazione API completa con esempi di richiesta e risposta per ogni endpoint. Il team mobile ha potuto integrare i nuovi endpoint in autonomia, senza bisogno di call di allineamento continue.
Risultati dopo 8 mesi in produzione
- 50.000 richieste al giorno gestite su un singolo server VPS da 20 euro/mese
- Tempo medio di risposta: 45ms — prima era 380ms (miglioramento dell 88%)
- Uptime: 99.97% in 8 mesi — 2 ore di downtime totali, entrambe per manutenzione programmata
- Zero incidenti di sicurezza: nessun accesso non autorizzato, nessun dato compromesso
- Tempo di sviluppo nuovi endpoint ridotto del 70% grazie alla struttura standardizzata
- Utenti attivi cresciuti da 2.000 a 5.200 senza necessita di scaling orizzontale
- Bug segnalati dal team mobile ridotti dell 85% grazie alla validazione e ai formati consistenti
Lezioni apprese sulla progettazione di API REST in PHP
Questo progetto mi ha insegnato che la consistenza e piu importante della perfezione. Un API con risposte sempre nello stesso formato, codici HTTP corretti e messaggi di errore utili e infinitamente piu facile da usare di un API con endpoint "intelligenti" che si comportano in modo diverso a seconda del contesto. Ho anche imparato che investire tempo nella documentazione riduce drasticamente il tempo di comunicazione con il team frontend/mobile — e un investimento che si ripaga in settimane, non in mesi.
Il backend ora gestisce il doppio del traffico iniziale senza necessita di scaling orizzontale. Quando servira scalare, l architettura pulita rendera l operazione prevedibile e gestibile.