Naming conventions

  • Use nouns, not verbs: /orders not /getOrders.
  • Plural resource names: /orders, /users, /products.
  • Lowercase with hyphens for multi-word resources: /order-items.
  • Nested resources for clear ownership: /orders/{id}/items.

Filtering and sorting

GET /orders?status=shipped&customer_id=42&sort=-created_at&limit=20
-- - prefix on sort field = descending

Sparse fieldsets

GET /orders?fields=id,status,amount
-- Returns only the requested fields — useful for mobile clients

Actions on resources

When an operation does not map cleanly to CRUD, use a sub-resource verb:

POST /orders/{id}/cancel
POST /orders/{id}/refund
POST /users/{id}/verify-email

HATEOAS

Include links to related resources and available actions in responses. Useful for generic clients. Adds response size. Practical middle ground: include a _links object on complex resources but do not require clients to use it for discovery.