Code-Memo

Resource Design

What a “resource” is in APIs

  1. A resource is anything with an identity you expose over the API: user, order, invoice, subscription, etc.
  2. Resources should map to domain concepts, not to every database row or internal job unless that is your product surface.
  3. Collections (/orders) and items (/orders/{id}) are the usual REST pattern.

Nouns vs verbs in endpoints

  1. Prefer nouns in paths (/orders, /orders/{id}) and express actions with HTTP methods or sub-resources (/orders/{id}/cancel is still debated; some use POST to a verb-like subpath, others model state transitions as PATCH).
  2. Avoid a zoo of verb endpoints (/createOrder, /getOrder) when HTTP already encodes verbs.
  3. Exception: RPC-style operations (reports, searches) sometimes fit better as POST /searches or a dedicated RPC layer.

Naming conventions (/users, /orders)

  1. Use plural nouns for collections (/users, /orders) for consistency.
  2. Use kebab-case or lowercase path segments; avoid spaces and ambiguous casing.
  3. Keep URLs readable in logs and stable for years (changing names is a breaking change).

Hierarchical resources (/users/{id}/orders)

  1. Nest when the child cannot exist meaningfully without the parent in your domain (/users/{id}/orders).
  2. Avoid deep trees (/a/b/c/d/e) that mirror internal storage too closely; flatten when the hierarchy does not help clients.
  3. Consider pagination and filtering at the collection level (/users/{id}/orders?status=open).