Best Practice per Design REST API

Best Practice per Design REST API

REST (Representational State Transfer) è uno stile architetturale per sistemi distribuiti. API REST ben progettate sono prevedibili, scalabili e developer-friendly.

Modellazione Risorse

Le risorse sono sostantivi, non verbi. Usa nomi plurali: /users, /orders, /products. Gerarchiche: /users/{id}/orders, /orders/{id}/items. Evita: /getUsers, /createOrder, /deleteUser. Identificatori: UUID preferito a ID sequenziali (sicurezza, sharding).

Semantica Metodi HTTP

GET: Recupera (safe, idempotent, cacheable). POST: Crea (non idempotent). PUT: Sostituisce intera risorsa (idempotent). PATCH: Aggiornamento parziale (non necessariamente idempotent). DELETE: Rimuove (idempotent). HEAD: Solo metadati. OPTIONS: Scopre capacità.

Status Code

2xx Successo: 200 OK, 201 Created (con header Location), 204 No Content. 3xx Redirect: 301 Moved Permanently, 304 Not Modified (caching). 4xx Errore Client: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity (validazione), 429 Too Many Requests. 5xx Errore Server: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Versioning

Versioning in URL: /api/v1/users (consigliato, esplicito). Versioning in header: Accept: application/vnd.myapi.v1+json. Query param: ?version=1 (evita). Non rompere mai versioni esistenti. Deprecare con header Sunset.

Paginazione, Filtraggio, Ordinamento

Cursor-based: ?after=cursor&limit=20 (preferito per performance). Offset-based: ?page=2&per_page=20 (semplice ma lento su dataset grandi). Filtraggio: ?status=active&created_after=2024-01-01. Ordinamento: ?sort=-created_at,name. Includi count totale in response meta.

Formato Risposta Errore

Struttura consistente: { error: { code: 'VALIDATION_ERROR', message: 'Input non valido', details: [{ field: 'email', issue: 'formato non valido' }] } }. Usa RFC 7807 (Problem Details for HTTP APIs): type, title, status, detail, instance.

Autenticazione e Autorizzazione

Bearer token (JWT) in header Authorization. API key per server-to-server. OAuth 2.0 per accesso delegato. Scopes/permessi in token. Rate limiting per client. Audit logging.

HATEOAS e Hypermedia

Hypermedia as the Engine of Application State. Includi link nelle risposte: { _links: { self: { href: '/users/1' }, orders: { href: '/users/1/orders' } } }. Abilita discoverability. Formati HAL, JSON:API, Siren.

Documentazione e Testing

Specifica OpenAPI 3.x (Swagger). Tool: Swagger UI, Redoc, Scalar. Contract testing: Pact, Schemathesis. Genera client: openapi-generator, orval. Mock server: Prism, WireMock.

Performance e Caching

ETag/If-None-Match per richieste condizionali. Header Cache-Control. CDN caching per GET. Compressione (gzip, Brotli). Connection pooling. Ottimizzazione query DB (problema N+1).