API Design Interview Questions

Summary

REST models the API as resources identified by URLs, manipulated with standard HTTP methods, using stateless requests and standard status codes and representations. Good practice: noun-based plural resources, correct methods and status codes, consistent JSON, pagination, filtering, versioning and clear errors.

Longer Answer

Examples: GET /orders?status=paid, POST /orders (201 + Location), GET /orders/42, PATCH /orders/42, DELETE /orders/42 (204), sub-resources GET /orders/42/items. Use actions sparingly when they don't fit CRUD (POST /orders/42/cancel). Keep naming consistent (snake_case or camelCase), use ISO 8601 dates and UTC, and document with OpenAPI.

Key Points

• Resources + HTTP methods
• Correct status codes
• Consistent naming and formats
• Pagination, filtering, versioning
• OpenAPI documentation

Summary

Safe methods (GET, HEAD, OPTIONS) don't change state; idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS) have the same effect whether called once or many times. POST and PATCH are not idempotent by default.

Longer Answer

Idempotency lets clients, proxies and SDKs retry safely after timeouts. Caches and crawlers assume GET is safe, so never change state on GET. Make POST retry-safe with idempotency keys.

Key Points

• Safe: no state change
• Idempotent: repeatable
• POST/PATCH need idempotency keys
• Never mutate on GET

Comparison / Tradeoffs

Summary

200 OK, 201 Created (with Location), 202 Accepted (async processing), 204 No Content; 400 Bad Request (malformed), 401 Unauthenticated, 403 Forbidden, 404 Not Found, 409 Conflict, 412 Precondition Failed, 422 Unprocessable Content (validation), 429 Too Many Requests; 500 Internal Error, 502/503/504 for upstream and availability problems.

Longer Answer

Be consistent and don't return 200 with an error body. Pair 4xx/5xx with a structured error body (RFC 9457 Problem Details), and include Retry-After for 429/503.

Key Points

• 2xx success variants
• 4xx client errors
• 5xx server/upstream errors
• No 200-with-error
• Retry-After for 429/503

Summary

Offset pagination (?page=3&size=20 → OFFSET 40 LIMIT 20) is simple and allows jumping to pages, but gets slow on deep pages and can skip or duplicate items when data changes. Cursor pagination returns an opaque cursor encoding the last seen sort key (WHERE (created_at, id) < (...) LIMIT 20), which is fast and stable but only supports next/previous.

Longer Answer

Use cursors for feeds, large tables and APIs consumed by machines; offsets for small admin lists that need page numbers. Always cap page size, use a deterministic sort with a unique tiebreaker, and return next_cursor (or Link headers).

Code Example

-- keyset pagination: next page after (created_at, id) of the last item
SELECT id, title, created_at
FROM posts
WHERE (created_at, id) < ($1, $2)
ORDER BY created_at DESC, id DESC
LIMIT 20;

Key Points

• Offset: simple, slow when deep, unstable
• Cursor: fast, stable, sequential
• Deterministic sort + tiebreaker
• Cap page sizes

Summary

Common approaches are URL path versioning (/v1/orders), header/media-type versioning (Accept: application/vnd.acme.v2+json) and date-based versions (Stripe's Stripe-Version: 2024-06-20). Whatever you choose, avoid breaking changes within a version, add fields compatibly, and deprecate with notice.

Longer Answer

Additive changes (new optional fields, new endpoints) don't need a new version; renames, removals, type changes and semantic changes do. Publish deprecation timelines with Deprecation/Sunset headers, monitor usage of old versions, and provide migration guides.

Key Points

• Path, header or date versions
• Additive changes are safe
• Breaking changes need versions
• Deprecation + Sunset headers

Summary

The client sends a unique Idempotency-Key header per logical operation; the server stores the key with a hash of the request and the resulting response, and if the same key arrives again it returns the stored response instead of performing the operation twice.

Longer Answer

Handle concurrent duplicates (lock or 'in progress' state returning 409), reject reuse of a key with a different payload, scope keys per client, and expire them after a retention window (e.g., 24h). Essential for payments and order creation.

Key Points

• Client-generated key per operation
• Store request hash + response
• Handle in-flight duplicates
• Expire keys

Summary

GraphQL suits client-driven data needs (many screens/clients needing different shapes, avoiding over/under-fetching) with a typed schema; REST suits resource-oriented public APIs with HTTP caching and simplicity; gRPC suits low-latency internal service-to-service calls with strict contracts and streaming.

Longer Answer

GraphQL trade-offs: caching complexity, N+1 resolvers, query cost control. gRPC trade-offs: browser support needs gRPC-Web/Connect, binary payloads are harder to debug. Many architectures use REST/GraphQL externally and gRPC internally.

Key Points

• GraphQL: flexible client queries
• REST: simple, cacheable, public
• gRPC: fast internal contracts
• Mix by audience

Comparison / Tradeoffs