How to design RESTful URL structures

· Category: API & REST

Short answer

RESTful URLs identify resources clearly and consistently, using nouns and hierarchy to express relationships.

Steps

  1. Use nouns to name resources, avoiding verbs in the path.
  2. Prefer plural nouns for collections, such as /invoices.
  3. Express subresources through nesting, like /customers/42/orders.
  4. Keep URLs lowercase and hyphenated for readability.
  5. Limit nesting depth to two or three levels to maintain simplicity.

Tips

  • Use query parameters for filtering, sorting, and pagination rather than additional path segments.
  • Avoid file extensions; rely on content negotiation via the Accept header.
  • Maintain backward compatibility when evolving URL structures.
  • Use UUIDs or opaque identifiers to prevent enumeration attacks.

Common issues

  • Deeply nested URLs becoming unwieldy and hard to cache.
  • Inconsistent pluralization confusing consumers.
  • Exposing internal database IDs that reveal implementation details.
  • Changing URLs without versioning, breaking existing clients.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.

Additional context

Applying these principles consistently across projects leads to more maintainable systems, clearer team communication, and better outcomes for end users. Regular review and refinement of practices ensure continuous improvement.