Anatomy of a REST URL
A REST endpoint is built from protocol, host, version prefix, resource, optional ID and
query string. Example: https://api.example.com/v1/users/42/orders?status=open.
Each part has a clear responsibility, and keeping them separate makes your API
predictable and easy to document.
Versioning
The /v1 prefix lets you ship breaking changes without breaking existing
clients. When you publish /v2, consumers migrate at their own pace. The
alternative is header-based versioning
(Accept: application/vnd.api+json;version=2), cleaner but less visible. For
public APIs, path versioning usually wins on clarity.
Plural resources and HTTP verbs
The most widespread rule: collection names always plural. /users,
/orders, /invoices. The HTTP verb decides the action: GET to
read, POST to create, PUT to replace, PATCH to update partially, DELETE to remove. Avoid
verbs in the URL: /users/create breaks the convention.
Path params vs query params
- Path params identify a specific resource:
/users/42. - Query params filter, sort, paginate:
?status=active&page=2. - Body carries data for create/update (POST, PUT, PATCH).
Resource nesting
For clear hierarchical relations: /users/42/orders lists orders of user 42.
Keep nesting to one level; /users/42/orders/7/items/3 gets unwieldy. If the
relation is ambiguous, use query params: /orders?user_id=42.
Pagination, filters and sorting
Three popular pagination patterns: offset/limit (?offset=40&limit=20),
page/size (?page=3&size=20) and cursor
(?cursor=abc&limit=20). Cursor scales best on large datasets. For sorting,
use a sort param with - prefix for descending:
?sort=-created_at,name.
Status codes
Return 2xx for success (200 OK, 201 Created, 204 No Content), 4xx for client errors (400,
401, 403, 404, 409, 422) and 5xx for server errors. Don't reuse 200 with an
{"error": ...} body; use the right code.
Document with OpenAPI
Once your conventions are set, document with OpenAPI (Swagger). You write YAML with every endpoint, params, responses and examples, and tools like Swagger UI or Redoc render it. Postman and Insomnia import OpenAPI and build collections automatically.