API Rest best practices

API Rest best practices. L’espressione “Application Programming Interface” o API si riferisce a un canale di comunicazione tra vari servizi software. Le applicazioni che trasmettono richieste e risposte sono chiamate rispettivamente client e server. Innanzitutto se siete dei completi neofiti, consigliamo di leggere prima il nostro articolo “Cosa sono le API”.

Esistono diversi tipi di protocolli API:

REST – si basa su un approccio client/server che separa il front-end e il back-end dell’API e fornisce una notevole flessibilità nello sviluppo e nell’implementazione.
RPC – Il protocollo RPC (Remote Procedural Call) invia più parametri e riceve i risultati.
SOAP – Supporta un’ampia gamma di protocolli di comunicazione presenti in Internet, come HTTP, SMTP e TCP.
WebSocket – Fornisce un modo per scambiare dati tra browser e server tramite una connessione persistente.
La maggior parte del lavoro quotidiano degli ingegneri del software utilizza o crea API REST. Il metodo standard di comunicazione tra i sistemi è attraverso le API. Pertanto, è fondamentale costruire le API REST in modo corretto per evitare problemi in futuro. Un’API ben definita deve essere facile da usare, concisa e difficile da usare in modo improprio.

Ecco alcune raccomandazioni generali di API Rest best practices.:

1. Usare nomi invece di verbi
   I verbi non dovrebbero essere usati nei percorsi degli endpoint. Il nome del percorso deve invece contenere i nomi che identificano l’oggetto a cui appartiene l’endpoint a cui si accede o che si modifica.

Ad esempio, invece di usare /getAllClients per recuperare tutti i client, usare /clients.

2. Utilizzare i sostantivi plurali delle risorse
   Utilizzate la forma plurale per i nomi delle risorse, perché si adatta a tutti i tipi di endpoint.

Per esempio, invece di usare /employee/:id/, usare /employees/:id/.

3. Essere coerenti
   Quando si dice essere coerenti, si intende essere prevedibili. Quando si definisce un endpoint, gli altri devono comportarsi in modo simile. Quindi, utilizzare lo stesso caso per le risorse, gli stessi metodi di autenticazione per tutti gli endpoint, le stesse intestazioni, gli stessi codici di stato, ecc.
4. Mantenere la semplicità
   Dovremmo fare in modo che la denominazione di tutti gli endpoint sia orientata alle risorse, così come sono. Se vogliamo definire un’API per gli utenti, la descriveremo come:

/users

/users/124

Quindi, la prima API ottiene tutti gli utenti e la seconda un utente specifico.

5. Codici di stato appropriati per l’utente
   Questo è molto importante. Esistono molti codici di stato HTTP, ma di solito ne usiamo solo alcuni. Non usatene troppi, ma usate gli stessi codici di stato per gli stessi risultati in tutta l’API, ad es,

200 per un successo generale.
201 per una creazione riuscita.
202 per una richiesta riuscita.
204 per nessun contenuto.
307 per il contenuto reindirizzato.
400 per richieste errate.
401 per richieste non autorizzate.
403 per autorizzazioni mancanti.
404 per mancanza di risorse.
5xx per errori interni.

6. Non restituire testo semplice
   Le API REST dovrebbero accettare JSON per il payload della richiesta e rispondere con JSON, perché è uno standard per il trasferimento dei dati. Tuttavia, non è sufficiente restituire un corpo con una stringa formattata in JSON; è necessario specificare un’intestazione Content-Type che sia application/JSON. L’unica eccezione è se stiamo cercando di inviare e ricevere file tra il client e il server.
7. Gestire correttamente gli errori
   Vogliamo eliminare ogni confusione quando si verifica un errore. Dobbiamo gestire gli errori in modo corretto e restituire un codice di risposta che indichi cosa è successo (da 400 a 5xx). Dobbiamo restituire alcuni dettagli nel corpo della risposta insieme al codice di stato.
8. Avere buone pratiche di sicurezza
   Vogliamo che tutte le comunicazioni tra un client e un server siano protette, il che significa che dobbiamo sempre usare SSL/TLS, senza eccezioni. Inoltre, consentire l’autenticazione tramite chiavi API, che devono passare utilizzando un’intestazione HTTP personalizzata con una data di scadenza.
9. Usare la paginazione
   Usare la paginazione se l’API deve restituire molti dati, per rendere l’API a prova di futuro. Si raccomanda l’uso di page e page_size.

Per esempio:

/products?page=10&page_size=20

10. Versione
    È essenziale versionare le API fin dalla prima versione, poiché le nostre API potrebbero avere diversi utenti. Ciò consentirà ai nostri utenti di non essere influenzati da modifiche che potremmo apportare in futuro. Le versioni delle API possono essere passate attraverso intestazioni HTTP o parametri di query/percorso.

Ad esempio, /prodotti/v1/4

Inoltre, non dimenticate di documentare le vostre API, perché l’API sarà efficiente solo quanto la sua documentazione. La documentazione dovrebbe mostrare esempi di cicli completi di richiesta/risposta. In questo caso, possiamo usare la definizione di OpenAPI come fonte di verità.

Per sviluppare le API, consultare le specifiche Swagger e OpenAPI, Postman o Stoplight.

(fonte)

Innovaformazione, scuola informatica specialistica promuove la cultura IT e lo sviluppo software. Trovate l’elenco corsi per aziende QUI.

INFO: info@innovaformazione.net – tel. 3471012275 (Dario Carrassi)