Skip to main content

REST API Design Workshop

Retrieval Prompts​

  1. State from memory the difference between PUT and PATCH, and explain why that difference matters for idempotency.
  2. Write the default response envelope for a paginated list endpoint.
  3. State the five HTTP status-code families and one example from each.
  4. Give three examples of URLs that should not be created, and explain why.
  5. Write a filter expression for "orders paid this month with total greater than 100" using a filter syntax of your choice, and identify the syntax.

Compare and Distinguish​

Separate these pairs cleanly:

  • GET /orders?filter=... vs POST /orders:search - when is each appropriate?
  • cursor pagination vs offset pagination - what breaks under concurrent writes?
  • PUT vs PATCH - what does each replace or update, and which is naturally idempotent?
  • 200 OK { ok: false } vs 4xx - what happens in real HTTP infrastructure for each?
  • URL-path versioning vs header versioning - who sees the version, and when does it matter?

Common Mistake Check​

Identify the error in each:

  1. POST /getUser/{id} retrieves a user by ID.
  2. DELETE /orders/{id} cancels an order by setting status: cancelled.
  3. GET /tickets returns all tickets in the system with no pagination - "we only have 8000, it'll be fine."
  4. Validation errors return 500 Internal Server Error with a message field.
  5. The API uses snake_case on some endpoints and camelCase on others because "the legacy endpoints predate the style guide."
  6. Pagination uses ?page=3&per_page=50 and the response has no tiebreaker in the sort.
  7. Errors on different endpoints have different shapes: { error: "..." }, { message: "..." }, { errors: [...] }.
  8. POST /payments has no idempotency mechanism and clients retry on timeout.

Mini Application​

Design a REST API for an online bookstore with these entities: book, author, customer, order, review. Produce:

  1. The full URL list for the five standard methods on each resource.
  2. Decide which relationships are nested and which are flat; justify.
  3. For each resource, name one custom method that the domain requires (e.g., books/{id}:republish, orders/{id}:refund) with its method, URL, request body, and success response.
  4. Design the pagination, filter, and sort for GET /books and GET /orders. Name the filterable fields.
  5. Write the canonical error envelope and three examples (validation, not found, conflict).
  6. Write the idempotency contract for POST /orders.

Constrain to 3 pages. If you cannot fit, your resource model is too large.

Evidence Check​

This page is complete only if, given a new domain, you can:

  • sketch the full resource URL list in under 20 minutes
  • defend each URL against the "nouns, plurals, hierarchy, no deep nesting" rules
  • match each endpoint to the correct verb, status codes, and idempotency mechanism
  • produce a pagination and filter design that handles concurrent writes and is bounded server-side
  • write the error envelope in a shape that is identical across every endpoint