RESTful API Design Questions

Focuses on designing resource oriented web APIs following Representational State Transfer principles and proper use of the Hypertext Transfer Protocol. Core skills include resource modeling and endpoint naming, use of correct Hypertext Transfer Protocol methods and semantics, status code selection and error response structure, idempotency and stateless design, request and response formats such as JavaScript Object Notation, pagination, filtering and sorting strategies, versioning and backward compatibility, authentication and authorization patterns, rate limiting and abuse prevention, caching and performance considerations, API contract testing and documentation, common anti patterns, and designing APIs that balance client usability with backend implementation concerns.

EasyTechnical

60 practiced

Describe common API versioning strategies (URI versioning, header versioning, content negotiation, and semantic versioning). For a public API choose and justify one approach and explain how you'd communicate deprecation and breaking changes to clients.

EasyTechnical

67 practiced

Design a query parameter strategy for filtering and sorting a resources list endpoint (for example: /products). Describe how to support multi-field sorting, range filters, boolean flags, enums, and full-text search while keeping parameters discoverable and unambiguous (suggest syntax examples).

MediumSystem Design

76 practiced

Design a rate-limiting strategy for a public REST API that must support bursty traffic and enforce per-user and per-endpoint limits. Explain algorithms you might use (token bucket, leaky bucket, fixed window, sliding window), how to communicate limits back to clients via headers, and how to implement these limits in a distributed environment.

Sample Answer

Requirements:- Per-user and per-endpoint limits- Support bursts (short spikes) and sustained rate control- Distributed API gateway layer, low latency, accurate enough (not strictly perfect)

High-level approach:- Use token-bucket per (user, endpoint) to allow bursts and enforce average rate. Backed by a global store for distributed enforcement.- Complement with a sliding-window counter for precise short-term fairness across replicas (helps prevent burst abuse when tokens resync).

Algorithms and when to use them:- Token Bucket: primary mechanism. Tokens accumulate at rate R; requests consume tokens; leftover tokens allow bursts up to bucket capacity B. Good for bursty traffic.- Leaky Bucket: enforces constant outflow (less flexible than token bucket) — use only if you need strictly steady pacing.- Fixed Window: simple, but suffers boundary spikes; not recommended alone.- Sliding Window Log/Counter: more accurate than fixed window for rate calculations; use sliding-window approximate counters (e.g., time-bucketed) to reduce state.

Architecture & components:1. API Gateway (edge): first check local cache of quota tokens for latency; if sufficient tokens, allow and decrement locally.2. Distributed Store: Redis (cluster) with atomic Lua scripts for token operations or a strongly-consistent KV like CockroachDB for stricter correctness.3. Shared cache (local LRU) per gateway to avoid roundtrips for every call; replenish from Redis periodically or on low tokens.4. Enforcement key: composite (user_id, endpoint_id). Store token_count, last_refill_ts, refill_rate, capacity.5. Fallback: if store unavailable, use conservative local limits or degrade to 429 with Retry-After.

Distributed implementation details:- Use Redis INCRBY/EXPIRE or Lua script to perform refill-and-consume atomically: compute tokens += (now - last_ts)*rate; cap at capacity; if tokens >= 1, subtract and allow; else deny.- To reduce cross-node contention, allow gateways to borrow a token credit window from Redis (lease N tokens) so most checks are local; on depletion request another lease.- For accuracy vs. performance trade-off, tune lease size and lease TTL.

Client communication:- Return standard headers on each response: - X-RateLimit-Limit: allowed capacity (e.g., 100/min) - X-RateLimit-Remaining: tokens left - X-RateLimit-Reset: seconds until refill or next window - Retry-After: seconds to wait on 429- Provide both per-endpoint and global headers when applicable (e.g., X-RateLimit-User-Limit).

Edge cases & trade-offs:- Clock skew: use monotonic server time for token calculations.- Bursty coordination: larger local leases increase throughput but may allow short-term overuse; smaller leases increase Redis calls.- Storage scale: shard Redis keys by user hash; TTL unused keys to reclaim memory.- Abuse: combine rate-limiting with authentication, throttling anonymous users more aggressively.

Monitoring and testing:- Emit metrics: denials, token refill rates, Redis latency, per-key hotness.- Load-test bursts to tune capacity and lease sizes.

This design balances burst tolerance (token bucket), short-term fairness (sliding-window approximations), and distributed efficiency (local caches + centralized atomic ops).

EasyTechnical

79 practiced

Describe best practices for designing JSON request and response payloads for a public REST API: naming conventions, envelope vs direct objects, error structure, timestamps/timezones, type hints, and handling optional/nullable fields. Provide a small JSON response example for a Product resource that follows your rules.

Sample Answer

Best practices (concise):

- Naming conventions: pick one and be consistent. For public JSON APIs, camelCase is common for JavaScript clients (e.g., productId, createdAt). Use plural resource names in endpoints (/products). Keep keys short but descriptive.- Envelope vs direct objects: return a direct resource object for single GETs. Use an envelope for collections or when you need metadata (pagination, rate-limit info) — e.g., { "data": [...], "meta": {...} }.- Error structure: standardized machine-readable errors with HTTP status, an error code, human message, optional details and requestId for tracing. Prefer a top-level "error" or "errors" key.- Timestamps/timezones: use ISO 8601 in UTC with Z (e.g., 2025-12-06T14:30:00Z). Always specify timezone and document format.- Type hints: declare types in your schema (OpenAPI/JSON Schema). Avoid embedding ad-hoc type strings in payloads except when needed for polymorphism (include "type": "digital" if behavior differs).- Optional/nullable fields: distinguish absent vs null. Prefer omitting absent optional fields; allow null only if semantically meaningful. Document which fields are nullable. For evolving APIs, add new optional fields (additive changes) and deprecate with versioning headers.

Small JSON response example (single Product GET):

json

{
  "productId": "prd_12345",
  "name": "Wireless Mouse",
  "description": "Ergonomic wireless mouse, black",
  "price": 29.99,
  "currency": "USD",
  "available": true,
  "tags": ["electronics", "accessories"],
  "createdAt": "2025-12-06T14:30:00Z",
  "updatedAt": "2025-12-10T09:15:00Z",
  "metadata": {
    "warrantyMonths": 12
  }
}

Error example (for reference):

json

{
  "error": {
    "status": 404,
    "code": "product_not_found",
    "message": "Product with id prd_99999 not found",
    "requestId": "req_abc123",
    "timestamp": "2025-12-06T14:45:00Z"
  }
}

HardTechnical

74 practiced

You rolled out a change that unintentionally broke a widely-used endpoint in production. As the engineer on-call describe the incident response steps you would take: immediate mitigation (rollback vs mitigation), communicating to stakeholders and customers, collecting telemetry and logs for root cause analysis, executing a postmortem, and action items to prevent recurrence.

Sample Answer

Situation: During a weekday deploy I pushed a change that unintentionally broke a widely-used GET endpoint; errors spiked from 0.1% to 60%, and several customers reported timeouts. I was the on-call engineer.

Task: Restore service quickly, communicate clearly, identify root cause, and put measures in place to prevent recurrence.

Action:- Immediate mitigation (first 0–15 minutes): - Assessed scope via monitoring (error rate, latency, affected hosts) and logs to confirm regression. - Made a fast decision to roll back the release because impact was broad and rollback was low-risk. Triggered the rollback playbook and deployed the previous artifact to all affected instances. - If rollback hadn’t been safe, I had fallback mitigations ready (feature flag off, rate-limiting, routing traffic away from bad instances).- Communication (0–30 minutes and ongoing): - Posted an incident notice in the incident channel and status page: what happened, who’s responding, initial ETA for recovery. - Notified Product, Support, SRE, and customer success with concise impact summary and next steps; updated every 15–30 minutes until resolved. - Sent a customer-facing update on the status page and via targeted email for impacted SLAs once we had resolution ETA.- Collecting telemetry & logs (during and after mitigation): - Captured distributed traces, request/response samples, and error stack traces from before the rollback window; snapshot logging and metrics to an isolated S3 bucket to preserve evidence. - Correlated deploy timestamps, config changes, and code diff to narrow scope. Replayed failing requests in a staging copy to reproduce.- Root cause analysis & postmortem (24–72 hours): - Led a blameless postmortem with stakeholders. Documented timeline, contributing factors (e.g., missing integration test, insufficient feature-flagging, gap in canary coverage), and evidence. - Assigned owners for each action item with deadlines and tracked in the sprint board.- Action items to prevent recurrence: - Add an automated end-to-end test that covers the endpoint and its common query patterns. - Enforce canary rollout for similar changes and require successful canary metrics before full rollout. - Introduce a pre-deploy checklist: feature-flag gating for risky changes and explicit rollback runbooks tested quarterly. - Improve monitoring: add alert for error-rate increase on high-impact endpoints with paging rules. - Run a tabletop incident drill within the quarter to exercise the playbook.

Result: Service restored within 12 minutes after rollback; stakeholder confidence maintained through transparent communication; follow-up changes reduced the likelihood of recurrence and shortened detection-to-recovery time in subsequent incidents.

Unlock Full Question Bank

Get access to hundreds of RESTful API Design interview questions and detailed answers.

Join thousands of developers preparing for their dream job.