Stai impostando correttamente gli endpoint dell'API REST?

Stai impostando correttamente gli endpoint REST API?

Stai impostando i tuoi endpoint API correttamente? Spesso quando impostiamo gli endpoint per le nostre API, ci troviamo di fronte a situazioni in cui non siamo sicuri se scrivere in forma plurale o singolare. Dovremmo usare trattini bassi o trattini? Come menzionare gli ID? Per un'API che crea una risorsa dovremmo usare /resource/create? E molto altro ancora. Quindi facciamo un'immersione profonda nelle convenzioni di denominazione per le REST API. Qui affronteremo:

• Endpoint
• Metodi
• Versionamento

Endpoint

Iniziamo esaminando alcune convenzioni di denominazione per le REST API.

Risorse come sostantivi

Le REST API dovrebbero consentirti di manipolare una risorsa utilizzando uno dei metodi HTTP principali. Gli URI REST non dovrebbero indicare alcun tipo di operazione CRUD. Dovrebbero riferirsi a una risorsa invece di un'azione/verbo. Quando possibile, utilizza solo forme plurali dei sostantivi, a meno che non si tratti di risorse singleton.

Buoni esempi:

• https://api.website.com/v1/store/products
• https://api.website.com/v1/store/customers
• https://api.website.com/v1/store/discounts

Cattivi esempi:

• https://api.website.com/v1/store/createproducts
• https://api.website.com/v1/store/updatecustomers
• https://api.website.com/v1/store/getdiscounts

Gerarchia

La gerarchia tra risorse e raccolte è definita dall'uso delle barre.

"Come in tutto il mestiere dello sviluppo software, la denominazione è fondamentale per il successo"

Buon esempio:

• https://api.website.com/v1/item/store

Cattivo esempio:

• https://api.website.com/v1/store/items

Trattini

È ampiamente accettato che leggere trattini ( first-name ) è più chiaro e user-friendly che leggere trattini bassi ( first_name ). Quindi, ogni volta che un endpoint REST API contiene più parole, è sempre meglio usare trattini al posto dei trattini bassi. Inoltre, c'è un aspetto dal punto di vista SEO. Si consiglia di utilizzare trattini in quanto aiutano i bot a identificare più facilmente i concetti nell'URL. E un trattino basso tra due parole è considerato nel complesso come una parola, mentre l'uso di trattini è considerato come due parole separate.

Buon esempio:

• https://api.website.com/v1/store/inventory-management/active-orders

Cattivo esempio

• https://api.website.com/v1/store/inventory_management/active_orders

Metodi

Ora sappiamo di non usare verbi nei nostri endpoint REST API, ma sorge la domanda su come specificare il verbo. Per questo, abbiamo i metodi HTTP in soccorso. I metodi HTTP sono i verbi che indicano il tipo di operazione che l'API potrebbe eseguire.

Metodi HTTP:

• GET corrisponde all'operazione di "lettura" di una risorsa o di una raccolta.
• POST corrisponde all'operazione di "creazione" di una risorsa o di una raccolta.
• PUT corrisponde all'operazione di "aggiornamento" di una risorsa o di una raccolta.
• DELETE corrisponde all'operazione di "eliminazione" di una risorsa o di una raccolta.

Esistono in totale 39 metodi HTTP, ma GET, POST, PUT e DELETE sono i metodi più comunemente usati e fondamentali. Affronteremo tutti i metodi HTTP e i loro casi di utilizzo in un blog separato.

Versionamento

È sempre meglio versionalizzare le tue API. Gli stessi URL possono essere consumati senza dover apportare modifiche importanti agli endpoint REST API. Gli endpoint dell'API non dovrebbero mai essere invalidati in quanto ciò potrebbe avere conseguenze impreviste per le applicazioni che li consumano.

Esempi:

• https://api.website.com/v1/store/items
• https://api.webiste.com/v2/store/employees

Punti chiave

• Usa sostantivi per rappresentare le risorse.
• Evita di usare verbi negli endpoint REST API.
• Non usare trattini bassi (`_`) in un endpoint. Usa piuttosto trattini (`-`).
• Usa query per filtrare, ordinare o limitare una raccolta API.
• Non aggiungere mai estensioni di file agli URL. Se vuoi specificare il tipo di contenuto, utilizza l'intestazione `Content-Type`.
• Preferisci sempre l'uso di lettere minuscole negli endpoint REST API.
• Non mettere barre finali (`/`) negli endpoint delle API Rest. Non aggiungono valore semantico e possono creare confusione.
• Scegli nomi semplici. Se fatto correttamente, gli endpoint dell'API diventeranno molto facili da ricordare o indovinare per qualsiasi sviluppatore.