Le Migliori Pratiche REST API – Esempi di Progettazione di Endpoint REST

Articolo originale: REST API Best Practices – REST Endpoint Design Examples

Nello sviluppo web, le API REST giocano un importante ruolo nell'assicurare una comunicazione regolare tra il client e il server.

Puoi pensare al client come al frontend e al server come al backend.

La comunicazione tra il client (frontend) e il server (backend) in genere non è proprio diretta. Quindi usiamo un'interfaccia chiamata Application Programming Interface (API) che agisce da intermediario tra il client e il server.

Poiché l'API gioca un ruolo cruciale in questa comunicazione client-server, dovremmo sempre progettare le API tenendo sempre presenti le migliori pratiche. Questo aiuta gli sviluppatori a mantenerle, e coloro che le adottano, allo stesso tempo, non incontrano problemi nell'utilizzarle.

In questo articolo, ti illustrerò 9 buone pratiche da seguire nella creazione di API REST. Questo ti aiuterà a creare le migliori API possibili, e anche a facilitare la vita ai suoi utilizzatori.

Innanzitutto, Cos'è una API REST?

REST sta per Representational State Transfer. È uno stile architetturale di software creato da Roy Fielding nel 2000 per orientare la progettazione di architetture per il web.

Qualunque API (Application Programming Interface) che segua i principi di progettazione  REST è detta RESTful.

In parole semplici, un'API REST è un mezzo per comunicare tra due computer via HTTP (Hypertext Transfer Protocol), allo stesso modo nel quale comunicano client e server.

Migliori Pratiche di Progettazione di API REST

1. Usare JSON come Formato per Inviare e Ricevere Dati

In passato, l'accettazione e la risposta relative a richieste API era effettuata per la maggior parte in XML e anche in HTML. Ma ai giorni nostri, JSON (JavaScript Object Notation) è diventato di gran lunga il formato de-facto per inviare e ricevere dati dalle API.

Questo perché, con il formato XML ad esempio, decodificare e codificare i dati è spesso una seccatura, pertanto il formato XML non è più ampiamente supportato dai framework.

JavaScript, per esempio, ha un metodo integrato per elaborare i dati JSON acquisiti via API in quanto JSON era stato creato principalmente per questo. Tuttavia se stai usando altri linguaggi di programmazione, come Python o PHP, anch'essi ora sono dotati di tutti i metodi per elaborare e manipolare i dati JSON.

Python, ad esempio, fornisce i metodi  json.loads() e json.dumps() per lavorare con i dati JSON.

Per assicurarti che il client interpreti correttamente i dati JSON, dovresti impostare il valore di Content-Type nell'header della risposta come application/json quando componi la richiesta.

Per quanto riguarda i framework lato server, molti di essi impostano automaticamente il valore di Content-Type. Express, per esempio, ora ha il middleware  express.json() per questo scopo. Anche il pacchetto NPM body-parser funziona ancora per lo stesso scopo.

2. Usare i Sostantivi Invece che i Verbi per gli Endpoint

Nella progettazione di un'API REST, non dovresti usare verbi nei percorsi degli endpoint. Gli endpoint dovrebbero usare sostantivi, che identificano ciò che ciascuno rappresenta.

Questo perché i metodi HTTP come GET, POST, PUT, PATCH e DELETE esprimono già una forma verbale (in lingua inglese) per l'esecuzione di operazioni CRUD di base.

GET, POST, PUT, PATCH e DELETE sono i verbi HTTP più comuni. Ce ne sono altri come COPY, PURGE, LINK, UNLINK e così via.

Quindi, per esempio, un endpoint non dovrebbe essere come questo:

https://mysite.com/ottieniPost

oppure

https://mysite.com/creaPost

Viceversa dovrebbe essere qualcosa come:

https://mysite.com/posts

In breve, dovresti lasciare che siano i verbi HTTP a rappresentare quello che fa un endpoint (ovviamente nel loro significato inglese - n.d.t). Pertanto GET otterrà dei dati, POST andrà a creare dati, PUT aggiornerà dati e DELETE si sbarazzerà dei dati.

3. Attribuire alle Collezioni Nomi al Plurale

Puoi pensare ai dati della tua API come una collezione di risorse diverse per i tuoi consumatori.

Se hai un endpoint come https://mysite.com/post/123, potrebbe andare bene per richieste di eliminazione (DELETE) o di aggiornamento (PUT o PATCH), ma non dice all'utente che potrebbero esserci altri post nella collezione. Ecco perché la tua collezione dovrebbe usare nomi plurali.

Quindi, invece di  https://mysite.com/post/123, dovrebbe essere https://mysite.com/posts/123.

4. Usare Codici di Stato nella Gestione degli Errori

Dovresti sempre usare normali codici di stato HTTP nelle risposte alle richieste fatte alla tua API. Questo aiuterà i tuoi utenti a sapere cosa sta succedendo: se la richiesta ha avuto successo, se ha fallito, o qualcosa d'altro.

Qui sotto c'è una tabella che mostra i vari gruppi di Codici di Stato HTTP e il loro significato:

5. Usare Annidamenti negli Endpoint per Mostrare Relazioni

Spesso, endpoint diversi possono essere interconnessi, pertanto li dovresti annidare per facilitarne la comprensione.

Per esempio, nel caso di una piattaforma di blog multi utente, diversi post potrebbero essere scritti da autori diversi, quindi un endpoint come https://mysite.com/posts/author, sarebbe un valido caso per l'annidamento.

Restando nello stesso ambito, i post potrebbero avere i loro commenti individuali, quindi per recuperare tutti i commenti di uno specifico post, un endpoint come https://mysite.com/posts/<postId>/comments dovrebbe avere senso.

Dovresti evitare di avere più di 3 livelli di annidamento, in quanto un numero superiore potrebbe rendere la tua API meno elegante e leggibile.

6. Usare Filtri, Ordinamento e Paginazione per Recuperare i Dati Richiesti

Talvolta un database di un'API potrebbe diventare incredibilmente grande. Se questo accade, ottenere dati da questo database potrebbe essere un'operazione molto lenta.

Il filtro, l'ordinamento e la paginazione sono tutte azioni che possono essere eseguite su una collezione di un'API REST. Ciò ti consente di recuperare, ordinare e disporre solo i dati necessari disposti in pagine in modo che il server non sia troppo occupato con le richieste.

Un esempio di un endpoint con filtro potrebbe essere il seguente:
https://mysite.com/posts?tags=javascript
Questo endpoint fornirà tutti i post che hanno un tag "JavaScript" associato.

7. Usare SSL per la Sicurezza

SSL sta per Secure Socket Layer. È cruciale per la sicurezza nella progettazione di API REST. Questo renderà sicura la tua API, che sarà meno vulnerabile ad attacchi dannosi.

Altre misure di sicurezza che dovrebbero essere prese in considerazione includono: rendere la comunicazione tra server e client privata e assicurarsi che nessun consumatore dell'API possa ottenere più di quello che sta richiedendo.

I certificati SSL non sono difficili da caricare su un server e sono sempre gratuiti come Let's Encrypt, molti altri solo per il primo anno. Non sono costosi da acquistare nel caso non fossero disponibili gratuitamente.

La chiara differenza tra l'url di un'API REST che viene eseguita su SSL rispetto a un'altra che non lo usa è la "s" che manca in HTTP per le richieste non sicure:
https://mysite.com/posts viene eseguita su SSL.
http://mysite.com/posts non viene eseguita su SSL.

8. Essere Chiari con il Versionamento

Le API REST dovrebbero avere versioni differenti, in modo da non forzare i client (gli utenti) a migrare a nuove versioni. Questo potrebbe anche non fare più funzionare la loro applicazione, se non sei cauto.

Uno dei più comuni sistemi di versionamento nello sviluppo web è il versionamento semantico.

Un esempio di versionamento semantico è 1.0.0, 2.1.2 e 3.3.4. Il primo numero rappresenta la versione major, il secondo la versione minor e il terzo la versione patch.

Molte API RESTful di giganti tecnologici e singoli in genere si presentano così:
https://mysite.com/v1/ per la versione 1
https://mysite.com/v2 per la versione 2

Facebook adotta questo versionamento per le proprie API:

Spotify adotta lo stesso sistema:

Questo non è il caso per tutte le API. Il versionamento adottato da Mailchimp per la sua API è diverso:

Quando rendi disponibile la tua API REST in questo modo, non forzi i client a migrare alla nuova versione nel caso scelgano di non farlo.

9. Fornire una Documentazione Accurata

Quando crei un'API REST, devi aiutare i client (chi utilizza la tua API) a conoscerla e scoprire come usarla correttamente. Il miglior modo per farlo è dotare l'API di una buona documentazione.

La documentazione dovrebbe contenere:

• gli endpoint rilevanti dell'API
• esempi di richieste per gli endpoint
• implementazioni in vari linguaggi di programmazione
• messaggi che elencano i diversi errori con i loro codici di stato

Uno degli strumenti comuni che puoi usare per documentare la tua API è Swagger. Puoi anche usare Postman, uno degli strumenti più diffusi tra gli sviluppatori web per i test delle API, per documentare le tue API.

Conclusione

In questo articolo, hai appreso diverse migliori pratiche da tenere a mente quando crei delle API REST.

È importante metterle in pratica in modo che tu possa costruire applicazioni altamente funzionali che funzionano bene, sono sicure e in ultima analisi facilitano la vita di chi utilizza la tua API.

Grazie per la lettura. Ora vai a creare qualche API usando queste migliori pratiche.