REST API Design Principles for Interviews
A clear, interview-ready way to design REST APIs: model resources, choose correct HTTP semantics, handle errors and pagination, and communicate tradeoffs crisply—then practice it in mock interviews to make it automatic in the real round.
What interviewers actually evaluate in REST API design
In interviews, “REST API design” is less about memorizing endpoints and more about demonstrating a consistent mental model: (1) identify resources and their relationships, (2) expose operations via HTTP methods with correct semantics (safety, idempotency), (3) define request/response contracts that are predictable (status codes, error shapes, pagination), and (4) make deliberate choices for cross-cutting concerns (auth, rate limits, versioning, observability). Strong candidates narrate assumptions, choose sensible defaults, and explicitly call out tradeoffs (simplicity vs flexibility, backward compatibility, performance, consistency).
An interview framework you can execute live in 10–15 minutes
1) Clarify the product flows and write 2–3 core use cases
Ask for the key client actions (create, list, update, search), expected scale (QPS, dataset size), and constraints (latency, mobile vs web). State the top use cases you will design for (e.g., “create an order”, “list a user’s orders”, “cancel an order”).
2) Model resources and relationships first (nouns, not verbs)
Identify primary resources and ownership boundaries (e.g., users, orders, line_items, products). Decide cardinalities and whether a subresource is nested (ownership) or referenced (shared). Keep URLs stable and resource-oriented.
3) Define endpoints with HTTP methods and idempotency in mind
Map actions to methods: GET (safe), POST (create/non-idempotent), PUT (replace/idempotent), PATCH (partial update), DELETE (idempotent delete). Call out idempotency keys for create operations that must be retry-safe (payments, order creation).
4) Specify request/response shapes and status codes
Define minimal required fields, server-generated fields, and consistent response envelopes. Use correct status codes (200/201/204, 400/401/403/404, 409, 422, 429, 5xx). Include Location header for 201 and return the created resource or a summary depending on payload size.
5) Handle listing at scale: pagination, filtering, sorting, and consistency
Choose pagination strategy: cursor-based for large/append-only feeds, offset-based for small/admin. Define filter and sort conventions (e.g., ?status=PAID&created_at_gte=...&sort=-created_at). Mention stable sort keys and eventual consistency caveats.
6) Design error responses that are debuggable and client-friendly
Standardize error shape (code, message, details, request_id). Differentiate validation errors vs conflicts. Ensure errors are consistent across endpoints and include field-level validation messages.
7) Address cross-cutting concerns explicitly
AuthN/AuthZ (OAuth2/JWT, scopes/roles), rate limiting (429 + Retry-After), versioning (prefer backward-compatible changes; otherwise /v1 or header), idempotency, and observability (request_id, trace headers). State what you are not designing due to time.
8) Sanity-check with the original use cases and edge cases
Walk through the API calls for each use case, including failure scenarios (duplicate creates, unauthorized access, partial failures). This is where interviewers see if your design is coherent end-to-end.
Common REST API interview mistakes that get noticed quickly
- •Using verbs in URLs (/createOrder, /doPayment) instead of resource-oriented nouns (/orders, /payments).
- •Misusing HTTP methods (POST for reads, GET with a request body, PUT for partial updates without acknowledging semantics).
- •Ignoring idempotency and retries—especially for create/payment-like operations where clients will retry on timeouts.
- •Hand-waving pagination (“we can paginate later”) or choosing offset pagination for large, frequently changing feeds without discussing consistency issues.
- •Inconsistent status codes and error shapes; returning 200 for everything or mixing validation and conflict errors.
- •Over-nesting resources (/users/{id}/orders/{id}/items/{id}/...) without explaining ownership or when to prefer references.
- •No story for authentication/authorization (who can access which resource) and no mention of rate limiting.
- •Versioning done as an afterthought, or proposing breaking changes without a migration plan.
- •Not walking through an end-to-end flow; endpoints look fine individually but don’t work together (missing IDs, missing transitions, unclear states).
- •Over-designing: too many endpoints and fields before confirming the core use cases and constraints.
Example: Designing an Orders API for an e-commerce checkout
Weak Answer
Endpoints: - POST /createOrder - POST /cancelOrder - POST /getOrders - POST /updateOrderStatus Request/response: - POST /getOrders {"userId": "123"} -> {"orders": [...]} - cancelOrder returns 200 even when the order is already shipped Notes: - No pagination, inconsistent response shapes - Uses POST for reads - No clear resource identifiers in URLs - Error responses vary per endpoint
Strong Answer
Resources: users, orders, order_items Core endpoints: - POST /v1/orders Body: {"user_id":"123","items":[{"product_id":"p1","qty":2}],"payment_method_id":"pm_9"} Headers: Idempotency-Key: "a1b2c3" Response: 201 Created Location: /v1/orders/o_789 Body: {"id":"o_789","status":"PENDING_PAYMENT","total_cents":4200,"created_at":"..."} - GET /v1/orders/o_789 Response: 200 OK + order details - GET /v1/users/123/orders?status=SHIPPED&limit=20&cursor=eyJjcmVhdGVkX2F0IjoiLi4uIn0&sort=-created_at Response: 200 OK {"data":[...],"next_cursor":"..."} - PATCH /v1/orders/o_789 Body: {"shipping_address": {...}} Response: 200 OK - POST /v1/orders/o_789/cancellations Response: - 201 if cancellation accepted - 409 Conflict if already shipped Standard error: - 409 {"error":{"code":"ORDER_NOT_CANCELLABLE","message":"Order already shipped","request_id":"...","details":{"status":"SHIPPED"}}}
Why it works
Decision quality: It models stable resources (orders, users) and uses HTTP semantics correctly, including idempotency for create and conflict handling for business rules. It scales listing with cursor pagination and explicit filters/sorts. Communication quality: The design ties back to concrete use cases (checkout, view order, list orders, cancel), calls out retry behavior via Idempotency-Key, and makes failure modes explicit with consistent, debuggable error payloads—exactly what interviewers look for under time pressure.
Why mock interviews are the fastest way to make REST principles usable
Knowing REST guidelines isn’t enough in interviews—you must apply them quickly while explaining tradeoffs clearly. Mock interviews force the real constraints: ambiguous requirements, limited time, follow-up questions, and pressure to stay consistent. On CrackTheOffer, you can practice realistic REST API design prompts (marketplace, messaging, payments, admin tooling), get feedback on semantics and clarity (methods, status codes, pagination, errors, versioning), and repeat until your framework becomes automatic for the real interview.