Come dare un nome agli endpoint delle API

Avete mai provato a chiedere indicazioni a qualcuno che vi descrive un percorso in modo super complicato? Ecco, con le API è un po’ la stessa cosa. Se non diamo un nome chiaro e semplice ai vari “posti” a cui vogliamo accedere, chi le userà si perderà in un labirinto di codice.

Perché è importante dare un nome giusto agli endpoint?

Immaginate di avere un’applicazione che gestisce un negozio online. Avrete bisogno di endpoint per gestire i prodotti, gli ordini, i clienti, ecc. Se chiamate l’endpoint che gestisce i prodotti “getAllProductsV2_beta_internal”, sarà difficile per chiunque altro capire cosa fa. Invece, se lo chiamate semplicemente “/products”, tutti capiranno subito che lì troveranno informazioni sui prodotti.

Le regole d’oro per i nomi degli endpoint

• Sostantivi, non verbi: Gli endpoint rappresentano delle risorse (prodotti, utenti, ecc.), quindi usiamo i nomi sostantivi. Invece di /getUser, scriviamo /users.
• Plurale per le collezioni: Se vogliamo tutti gli utenti, scriviamo /users. Se vogliamo un solo utente, aggiungiamo l’ID: /users/123.
• Verbi HTTP per le azioni:
  • GET: per prendere qualcosa (es. GET /products per prendere tutti i prodotti)
  • POST: per creare qualcosa (es. POST /products per creare un nuovo prodotto)
  • PUT: per aggiornare completamente qualcosa (es. PUT /products/123 per aggiornare completamente il prodotto con ID 123)
  • PATCH: per aggiornare parzialmente qualcosa (es. PATCH /products/123 per aggiornare solo il nome del prodotto con ID 123)
  • DELETE: per eliminare qualcosa (es. DELETE /products/123 per eliminare il prodotto con ID 123)
• Struttura gerarchica: Se ci sono relazioni tra le risorse, usiamo una struttura a livelli (es. /users/123/orders per vedere gli ordini dell’utente con ID 123).
• Nomi semplici e intuitivi: Evitate abbreviazioni strane o termini troppo tecnici.
• Versionamento: Se cambiate qualcosa in modo importante, aggiungete una versione (es. /v2/products).
• Parametri di query: Per filtri o ordinamenti, usate i parametri di query (es. /products?category=elettronica).

Esempi pratici

Un’API per una libreria: GET /books POST /books GET /books/123 PUT /books/123 DELETE /books/123 GET /authors GET /authors/123/books (libri di un autore specifico)

Un’API per un social network:

• GET /users
• POST /users
• GET /users/123/posts
• POST /users/123/posts
• GET /posts?tag=programmazione

Perché è così importante? Dare dei nomi chiari e coerenti agli endpoint è come fornire una mappa dettagliata a chi vuole usare la vostra API. Questo renderà più facile per gli sviluppatori capire come interagire con la vostra applicazione e vi farà guadagnare punti in termini di usabilità e manutenibilità del codice.

Esercizi

1. Crea un’API per un blog: Quali endpoint ti servono? Come li chiameresti?
2. Crea un’API per un’applicazione di to-do list: Stessa domanda.
3. Analizza un’API esistente (es. l’API di GitHub): Come sono chiamati gli endpoint? Seguono le regole che abbiamo visto?