Un'API ben progettata è invisibile. Gli sviluppatori la usano senza pensarci, tutto funziona come si aspettano. Un'API mal progettata genera frustrazione, bug, e ticket di supporto. Ecco come fare la prima.
Naming che ha senso
Risorse al plurale: /users, non /user. Nomi, non verbi: GET /orders, non GET /getOrders. Il metodo HTTP esprime già l'azione.
Relazioni nidificate: /users/123/orders per gli ordini dell'utente 123. Chiaro, prevedibile, RESTful.
Versioning fin dal giorno uno
Prefisso URL (/v1/users) o header. Scegliete uno e siate coerenti. Anche se oggi non pensate di avere più versioni, iniziate comunque. Cambiare dopo è doloroso.
Errori informativi
Status code appropriato (400 per errori client, 500 per server). Body con dettagli: codice errore, messaggio umano, eventualmente campo coinvolto. Gli sviluppatori debuggano più velocemente.
Pagination fin da subito
Anche se oggi avete 10 utenti, implementate pagination. ?page=1&limit=20 o cursor-based per dataset grandi. Aggiungete sempre metadata: totale elementi, pagina corrente, link prossima pagina.
Documentazione automatica
OpenAPI/Swagger genera documentazione dal codice. I client possono generare SDK automaticamente. Investite nel setup iniziale, risparmiate ore di comunicazione.