API REST Best Practices 2025: Guida Completa

Le API REST sono la spina dorsale del web moderno. Ogni app mobile, ogni SaaS, ogni integrazione tra servizi si basa su chiamate REST. Ma c'è una differenza enorme tra un'API che "funziona" e un'API ben progettata. Una buona API è intuitiva, sicura, performante e facile da evolvere. Vediamo le best practice che nel 2025 distinguono le API professionali da quelle amatoriali.

Design delle risorse: la base di tutto

Il primo errore che vedo nelle API è usare verbi negli endpoint. REST si basa sulle risorse (nomi), non sulle azioni (verbi). I metodi HTTP già esprimono l'azione.

// Sbagliato
GET /getUsers
POST /createUser
DELETE /deleteUser/123

// Corretto
GET /users           // lista utenti
POST /users          // crea utente
GET /users/123       // singolo utente
PUT /users/123       // aggiorna utente
DELETE /users/123    // elimina utente

Regole per gli endpoint

• Usa plurale e lowercase: /users, /orders, /products
• Usa kebab-case per nomi composti: /order-items, non /orderItems o /order_items
• Gerarchia max 2 livelli: /users/123/orders va bene, /users/123/orders/456/items/789 è troppo profondo
• Evita estensioni: /users, non /users.json (usa l'header Accept invece)

Metodi HTTP: ognuno ha il suo scopo

L'idempotenza è cruciale: chiamare lo stesso endpoint PUT o DELETE più volte produce sempre lo stesso risultato. Questo permette retry sicuri in caso di errori di rete.

Status code HTTP: comunicare chiaramente

Gli status code non sono optional. Restituire sempre 200 con un campo "error" nel body è un antipattern che complica la vita ai client.

// Status code essenziali
200 OK              // Richiesta riuscita
201 Created         // Risorsa creata (POST)
204 No Content      // Successo senza body (DELETE)
400 Bad Request     // Errore client (validazione, formato)
401 Unauthorized    // Non autenticato
403 Forbidden       // Autenticato ma non autorizzato
404 Not Found       // Risorsa non esiste
409 Conflict        // Conflitto (es. duplicato)
422 Unprocessable   // Entità valida ma non processabile
429 Too Many Reqs   // Rate limit superato
500 Internal Error  // Errore server

Versionamento: proteggere i client esistenti

Le API evolvono, ma i client no. Un breaking change senza versionamento rompe tutte le integrazioni. Nel 2025 le strategie più usate sono tre:

1. URL versioning (raccomandato)

GET /v1/users
GET /v2/users

Semplice, esplicito, facile da gestire nel routing. È lo standard de facto.

2. Header versioning

GET /users
Accept: application/vnd.api+json;version=2

Più "puro" secondo REST, ma meno intuitivo per sviluppatori e testing.

3. Query parameter

GET /users?version=2

Semplice ma meno elegante, può interferire con altri parametri.

Consiglio: usa URL versioning (/v1/) e mantieni supporto per almeno 2 versioni durante le transizioni. Comunica le deprecazioni con header Deprecation e Sunset.

Autenticazione: OAuth 2.1 e JWT nel 2025

OAuth 2.1 (ratificato nel 2024) è lo standard per l'autenticazione API. Consolida le best practice di OAuth 2.0 e rimuove i flow deprecati.

Flow raccomandati

• Authorization Code + PKCE: per app web e mobile
• Client Credentials: per comunicazione server-to-server
• Refresh Token: per rinnovare access token scaduti

// Header di autenticazione standard
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// JWT payload tipico
{
  "sub": "user-uuid",
  "email": "user@example.com",
  "role": "admin",
  "iat": 1704067200,
  "exp": 1704153600
}

Best practice sicurezza token

• Access token brevi (15-60 minuti)
• Refresh token più lunghi ma revocabili
• Firma con algoritmo asimmetrico (RS256) per JWT pubblici
• Mai esporre secret key nel client

Rate limiting: proteggere l'API

Senza rate limiting, un singolo client può sovraccaricare l'intera infrastruttura. Implementa limiti e comunicali chiaramente:

// Header di risposta
X-RateLimit-Limit: 1000        // Limite totale
X-RateLimit-Remaining: 847     // Richieste rimanenti
X-RateLimit-Reset: 1704067200  // Timestamp reset

// Quando superato
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Strategie comuni: limite per IP, per API key, per utente. Considera limiti diversi per endpoint critici (es. login più basso di /products).

Paginazione: gestire grandi dataset

Mai restituire migliaia di record in una singola risposta. La paginazione è obbligatoria per qualsiasi lista.

Offset-based (semplice)

GET /users?page=2&limit=20

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Cursor-based (performante)

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

{
  "data": [...],
  "meta": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}

Cursor-based è più efficiente per dataset grandi e in evoluzione, offset-based è più semplice da implementare e usare.

Filtri e ordinamento: query flessibili

// Filtri
GET /orders?status=pending&userId=123

// Ordinamento
GET /products?sort=price:asc,createdAt:desc

// Ricerca
GET /users?search=mario

// Campi specifici (sparse fields)
GET /users?fields=id,name,email

Documenta sempre quali filtri sono supportati. Valida i parametri e restituisci 400 per valori non riconosciuti.

Gestione errori: essere utili

Un errore ben formato aiuta lo sviluppatore a risolvere il problema. Un errore generico lo fa impazzire.

// Errore ben formato
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {"field": "email", "message": "Invalid email format"},
      {"field": "password", "message": "Minimum 8 characters"}
    ],
    "requestId": "req_abc123"
  }
}

// Mai fare questo
{
  "error": "Something went wrong"
}

Includi sempre un requestId per correlare errori con i log server. È fondamentale per il debugging in produzione.

Sicurezza: le basi non negoziabili

• HTTPS obbligatorio: nessuna eccezione, nemmeno in sviluppo
• API key in header: mai in URL (vengono loggati)
• Rotazione chiavi: almeno ogni 90 giorni
• Secrets management: HashiCorp Vault, AWS Secrets Manager
• Input validation: sanitizza tutto, mai fidarsi del client
• CORS configurato: limita i domini autorizzati

Documentazione: OpenAPI è lo standard

Una API senza documentazione è inutilizzabile. OpenAPI (ex Swagger) 3.1 è lo standard nel 2025:

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

Genera la documentazione dal codice o vice versa. Mantienila sincronizzata o diventa rapidamente obsoleta.

Conclusione

Le best practice REST non sono teoria accademica: sono lezioni apprese da milioni di API in produzione. Seguirle significa meno bug, meno frustrazione per chi integra la tua API, e meno problemi quando dovrai farla evolvere. I punti chiave:

• Risorse con nomi plurali, gerarchia piatta
• Metodi HTTP e status code corretti
• Versionamento URL (/v1/) per proteggere i client
• OAuth 2.1 con JWT per autenticazione
• Rate limiting con header espliciti
• Paginazione obbligatoria per liste
• Errori dettagliati con requestId
• OpenAPI per documentazione

Se stai costruendo una nuova API nel 2025, queste pratiche non sono opzionali: sono il minimo per essere presi sul serio come sviluppatori.