Best Practice di Progettazione API REST: La Guida Completa

Progettare una buona API REST significa molto piu che restituire JSON. Un'API ben progettata e prevedibile, coerente, sicura e facile da consumare. Questa guida copre le migliori pratiche di progettazione API REST.

1. Usare nomi per le URI delle risorse

Le API REST modellano risorse, non azioni.

# Good - nouns representing resources
GET    /api/v1/users          # list users
GET    /api/v1/users/123      # get user 123
POST   /api/v1/users          # create a user
PUT    /api/v1/users/123      # replace user 123
PATCH  /api/v1/users/123      # partially update user 123
DELETE /api/v1/users/123      # delete user 123

# Bad - verbs describing actions
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser/123
GET    /api/v1/getUserById?id=123

# Nested resources (one level deep)
GET    /api/v1/users/123/orders       # orders for user 123
GET    /api/v1/users/123/orders/456   # order 456 for user 123
POST   /api/v1/users/123/orders       # create order for user 123

# For actions that don't map to CRUD, use sub-resources
POST   /api/v1/users/123/activate     # activate user (action)
POST   /api/v1/orders/456/cancel      # cancel order (action)
POST   /api/v1/emails/789/resend      # resend email

2. Usare i metodi HTTP correttamente

Ogni metodo HTTP ha un significato semantico specifico.

Method	Purpose	Idempotent	Request Body
`GET`	Read a resource	Yes	No
`POST`	Create a resource	No	Yes
`PUT`	Full replacement	Yes	Yes
`PATCH`	Partial update	No*	Yes
`DELETE`	Remove a resource	Yes	No

3. Usare nomi di risorse al plurale

Usa sempre nomi al plurale per le collezioni.

# Good - consistent plural nouns
/api/v1/users
/api/v1/users/123
/api/v1/products
/api/v1/products/456/reviews

# Bad - mixing singular and plural
/api/v1/user          # singular
/api/v1/user/123
/api/v1/productList   # avoid "list" suffix

4. Usare i codici di stato HTTP correttamente

I codici di stato indicano al client cosa e successo.

Code	When to Use
`200 OK`	Successful GET, PUT, PATCH, or DELETE
`201 Created`	Successful POST that creates a resource
`204 No Content`	Successful DELETE with no response body
`400 Bad Request`	Malformed request syntax or invalid data
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Authenticated but not authorized
`404 Not Found`	Resource does not exist
`409 Conflict`	Conflicting state (e.g., duplicate email)
`422 Unprocessable`	Validation errors in request body
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Error`	Unexpected server error

5. Versionare la tua API

Il versionamento protegge i consumatori esistenti durante modifiche incompatibili.

# Strategy 1: URI versioning (most common)
GET /api/v1/users
GET /api/v2/users

# Strategy 2: Header versioning
GET /api/users
Accept: application/vnd.myapi.v2+json

# Strategy 3: Query parameter versioning
GET /api/users?version=2

Strategy	Pros	Cons
URI path	Simple, visible, cacheable	URI pollution
Header	Clean URIs	Harder to test, less visible
Query param	Easy to add	Cache-unfriendly, easy to forget

6. Paginazione, filtraggio e ordinamento

Ogni endpoint che restituisce una collezione deve supportare la paginazione.

# Offset-based pagination (simplest)
GET /api/v1/users?page=2&limit=25
GET /api/v1/users?offset=25&limit=25

# Cursor-based pagination (better for large datasets)
GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=25

# Response with pagination metadata
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "page": 2,
    "limit": 25,
    "totalPages": 50,
    "hasNext": true,
    "hasPrev": true
  }
}

# Filtering and sorting
GET /api/v1/products?category=electronics&minPrice=100&maxPrice=500
GET /api/v1/products?sort=price&order=asc
GET /api/v1/products?sort=-created_at  # prefix with - for descending
GET /api/v1/users?fields=id,name,email  # sparse fieldsets

7. Formato di risposta errore

Un formato di errore coerente aiuta i client a gestire gli errori programmaticamente.

// Consistent error response format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      },
      {
        "field": "age",
        "message": "Must be at least 18",
        "value": 15
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2026-01-15T10:30:00Z",
    "docs": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

// Simple error (non-validation)
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with id 999 not found",
    "requestId": "req_def456"
  }
}

8. Autenticazione e sicurezza

La sicurezza API e irrinunciabile.

# Bearer token authentication (JWT)
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

# API key authentication
GET /api/v1/users
X-API-Key: sk_live_abc123def456

# OAuth 2.0 token request
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=read:users write:users

Always use HTTPS in production
Never put secrets in query parameters (they appear in server logs)
Use short-lived access tokens (15-60 min) with refresh tokens
Implement CORS properly for browser-based clients
Validate and sanitize all input to prevent injection attacks
Use rate limiting to prevent brute-force attacks

9. Limitazione della frequenza

La limitazione della frequenza protegge la tua API dagli abusi.

# Rate limit response headers (standard)
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000        # max requests per window
X-RateLimit-Remaining: 742     # requests remaining
X-RateLimit-Reset: 1706810400  # Unix timestamp when limit resets
Retry-After: 60                # seconds until next request (on 429)

# Rate limit exceeded response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Limit: 1000/hour",
    "retryAfter": 60
  }
}

10. HATEOAS e link

HATEOAS aggiunge scopribilita alla tua API.

// HATEOAS response example
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "status": "active",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "deactivate": {
      "href": "/api/v1/users/123/deactivate",
      "method": "POST"
    }
  }
}

// Paginated collection with HATEOAS links
{
  "data": [...],
  "_links": {
    "self": { "href": "/api/v1/users?page=2&limit=25" },
    "first": { "href": "/api/v1/users?page=1&limit=25" },
    "prev": { "href": "/api/v1/users?page=1&limit=25" },
    "next": { "href": "/api/v1/users?page=3&limit=25" },
    "last": { "href": "/api/v1/users?page=50&limit=25" }
  }
}

Domande frequenti

PUT o PATCH per gli aggiornamenti?

PUT per sostituzione completa, PATCH per aggiornamento parziale.

Le URI devono essere minuscole?

Si, usa il kebab-case in minuscolo.

Come gestire le risorse annidate?

Limita l'annidamento a un livello.

Miglior metodo di autenticazione?

OAuth 2.0 con JWT per le app orientate all'utente.

GraphQL o REST?

REST e piu semplice con migliore caching. GraphQL per esigenze dati complesse.

TL;DR

Use nouns (not verbs) for resource URIs
Use the correct HTTP method for each operation
Always use plural resource names
Return appropriate HTTP status codes
Version your API from day one (URI path is simplest)
Support pagination, filtering, and sorting for collections
Use a consistent error response format
Always use HTTPS and proper authentication
Implement rate limiting with standard headers
Consider HATEOAS for API discoverability

Seguire queste best practice dall'inizio risparmia ore di refactoring.