Resource Design

• Everything is a resource (a noun) at a URI
• Clients exchange representations (usually JSON) of its state

• Client-server: UI and data split
• Stateless: each request carries all context (token, params)
• Cacheable: responses declare it
• Uniform interface: standard verbs and URIs
• Layered system: proxies, gateways
• Code-on-demand: optional

• Of these five, only GET is safe (HEAD and OPTIONS are safe too)

• RESTful vs just HTTP? Resources plus all six constraints
• Why stateless? Any server serves any request, so it scales out
• Safe vs idempotent? Safe: GET. Idempotent: GET, PUT, DELETE

• Plural nouns, lowercase kebab-case
• Never verbs: the HTTP method is the verb

• Nest only to show ownership, 1-2 levels deep
• Item has a unique ID? Expose it at top level: /orders/42
• Keep the nested path for listing: /users/7/orders

• Non-CRUD action: model a noun sub-resource, not a verb
• Cancel an order: POST /orders/42/cancellation

• Filter, sort and paginate with query params
• Cursor pagination for large or changing data
• Offset slows down and skips or duplicates rows as data shifts

• Send JSON with Content-Type: application/json
• PUT needs the full object; PATCH sends only changed fields
• Return the created or updated resource

{ "type": "...",
  "title": "Validation failed",
  "status": 422,
  "detail": "email is invalid",
  "errors": [{ "field": "email" }] }

RFC 9457 problem+json shape

• Responses carry links to the next valid actions
• Clients follow links instead of hardcoding URLs
• Most real APIs skip it

{ "id": 42, "status": "pending",
  "_links": {
    "pay": "/orders/42/payment",
    "cancel": "/orders/42" } }

the server decides which actions are open

• What does HATEOAS solve? Hardcoded URLs: links tell clients the next valid actions
• GraphQL over REST? Varied clients that need exact fields
• gRPC over REST? Fast internal calls with a strict contract
• Why is GraphQL caching harder? One endpoint, so URL-keyed HTTP caches cannot tell queries apart

• GET that changes state breaks the safe contract
• Crawlers and prefetchers fire it: side effects
• 200 + error hides failures from clients and monitoring

• Add /v1 or a version header from day one
• Put a limit on every collection, with a max cap
• Unbounded lists break later: slow, huge payloads

GET /v1/orders?limit=20&cursor=abc

version + limit + cursor

• Version a public API? /v1 in path or a header; keep old versions alive
• No pagination? Huge responses, timeouts, memory pressure as data grows
• Errors as 200? Clients, caches and monitoring read only the status code

• Plural nouns, kebab-case, nest at most two levels
• Filter, sort and paginate with query params
• - prefix on sort means descending

• REST: public CRUD APIs
• GraphQL: flexible client-driven queries
• gRPC: fast internal service calls
• HATEOAS is optional