Design URL API RESTful: Guida agli Endpoint per Sviluppatori

Best practice per il design di endpoint API RESTful. Crea strutture URL API pulite, coerenti e scalabili.

Nel design di API RESTful, la struttura URL influisce direttamente sull'usabilità e manutenibilità della tua API. In questa guida, impariamo a progettare endpoint API developer-friendly.

Fondamenti REST

Cos'è REST?

Representational State Transfer (REST) è uno stile architetturale per API web. Rappresenta risorse attraverso URL e usa metodi HTTP.

Metodi HTTP

GET    → Leggere risorsa
POST   → Creare nuova risorsa
PUT    → Sostituire risorsa completamente
PATCH  → Aggiornare risorsa parzialmente
DELETE → Eliminare risorsa

Principi di Design URL

1. Usare Sostantivi, Non Verbi

# SBAGLIATO - Usando verbi
GET  /getUsers
POST /createUser

# CORRETTO - Usando sostantivi
GET    /users
POST   /users

2. Usare Sostantivi Plurali

# SBAGLIATO
/user
/product

# CORRETTO
/users
/products

3. Struttura Gerarchica

# Ordini dell'utente
GET /users/123/orders

# Articoli dell'ordine
GET /orders/456/items

Versionamento

Versione nell'URL

# Metodo più comune
https://api.example.com/v1/users
https://api.example.com/v2/users

Filtraggio, Ordinamento e Paginazione

Filtraggio

# Filtraggio semplice
GET /products?category=electronics

# Operatori di confronto
GET /products?price[gte]=100&price[lte]=500

Ordinamento

# Ordinamento per un campo
GET /products?sort=price
GET /products?sort=-price        # Decrescente

Paginazione

# Basata su offset
GET /products?page=2&per_page=20

# Basata su cursore (più performante)
GET /products?cursor=abc123&limit=20

Codici di Stato HTTP

# Successo
200 OK           → GET, PUT, PATCH riuscito
201 Created      → POST riuscito
204 No Content   → DELETE riuscito

# Errori Client
400 Bad Request  → Richiesta non valida
401 Unauthorized → Autenticazione richiesta
403 Forbidden    → Nessun permesso
404 Not Found    → Risorsa non trovata

Conclusione

URL di API ben progettati aumentano l'usabilità della tua API e facilitano la manutenzione. Crea API developer-friendly usando nomenclatura coerente, gerarchia logica e metodi HTTP standard.