Negli ultimi anni lo sviluppo di web API si è notevolmente incrementato a seguito della diffusione di client etereogenei e di nuove tecnologie: PC desktop, dispositivi mobili come cellulari e tablet, IOT (Internet of Things), Big Data, usano tutti interfacce web based per connettere e aggregare componenti e dati distribuiti al fine di creare sempre nuove soluzioni/servizi per qualsisi tipo di business globale. E’ nata per questo la necessità di creare dei sistemi di backend “neutrali” che forniscono dati in maniera “grezza” (tipicamente nel formato JSON o XML) che poi vengono utilizzati opportunamente sulle varie tipologie di dispositivi. Il modello adottato per la progettazione delle API è l ‘ormai conslidato REST.

In breve, questo modello consente di strutturare le API in risorse logiche su cui si opera mediante il protocollo HTPP usando le operazioni standard che quest’ultimo ci mette a disposizione, quindi: GET, POST, PUT e DELETE.

Esula da questo articolo l’approfondire il modello REST; fornirò alla fine un elenco di risorse utili per chi volesse approfondire l’argomento. Qui invece verrano descritte 10 best pactices per progettare/sviluppare una API in maniera chiara e pulita. L'utilizzo di metodologie e convenzioni chiare e predefinite consente meglio di condividere le informazioni tra sviluppatori, architetti e designer al fine di migliorare tutto il ciclo di implementazione di una web API.

Ma vediamo l’elenco delle 10 best practices:

Indice

1. Usare Nomi e non Verbi
2. Usare i Nomi al plurale
3. GET e parametri di query non dovrebbero alterare lo stato
4. Usa le sub-resources per descrivere le relazioni
5. Usa gli header HTTP per definire i formati di serializzazione dei dati
6. Use HATEOAS
7. Implementa operazioni di filtraggio, ordinamento, selezione di specifici campi e paginazione per le collection: Filtraggio, Ordinamento, Selezione di campi, Paginazione
8. Versiona la tua API
9. Gestisci gli errori usando i codici di stato HTTP: Usa il payload dell’errore
10. Consenti l’override dei metodi HTTP