REST API: Architecture, Practice & Interviews

What is a REST API, what are the REST architectural constraints, how REST differs from a simple HTTP API, and what problems appear when REST principles are followed only superficially?

What does statelessness mean in REST API design, including client-side state management, its impact on scalability, and the limitations it creates for user sessions?

What is resource-oriented design in REST APIs, including modeling entities as resources, choosing URIs, and the problems of representing business actions as resources?

How should resource URIs be designed in REST APIs, including nesting, readability, long-term stability, and the limitations of deeply nested hierarchies?

How should HTTP methods be selected in REST APIs, including GET, POST, PUT, PATCH, DELETE, and what problems arise when methods are used incorrectly for business operations?

What does a safe HTTP method mean, including the behavior of GET, its impact on caching, and the problems caused by performing state-changing operations through GET?

What is idempotency in HTTP methods, and how do PUT and DELETE behave? How does idempotency differ from safety, and what are the consequences for retrying requests after network failures?

How should HTTP status codes be used in REST APIs, including 2xx, 3xx, 4xx, 5xx, and the problems caused by returning every error as 200 OK?

How should 400, 401, 403, 404, 409, and 422 errors be distinguished in REST APIs, and what are practical use cases and risks of ambiguous handling?

How should a REST API response format be designed, including envelopes, payloads, metadata, and the trade-offs between consistency and excessive response verbosity?

How should an error response format be designed in REST APIs, including machine-readable codes, human-readable messages, details, trace IDs, and the risks of exposing internal system information?

Краткое руководство по использованию HTTP‑заголовков в REST API.

How to design a REST API contract: request and response schemas, required fields, and handling backward compatibility when the contract changes.

How should REST API documentation be organized, including request examples, error examples, usage scenarios, and the problem of documentation becoming outdated compared to implementation?

How should request validation be designed in REST APIs, including type checks, required fields, business constraints, and the difference between syntactic and domain errors?

What is the OpenAPI Specification, including endpoint descriptions, schemas, parameters, errors, and limits of generating docs automatically from code?

Short answer: Response validation ensures responses conform to the agreed contract (schema), prevents accidental breaking changes by catching deviations early, and is essential for reliable integration testing between services.

How should REST API schema changes be managed, including adding new fields, removing old fields, changing field types, and the risks for existing clients?

How should nullable and optional fields be designed in REST APIs, and what is the difference between missing, null and empty values? Which problems arise during partial updates and how to avoid them?

How should enum fields be designed in REST APIs, including extensibility of values, behavior of old clients, and the problems caused by strict client-side validation?

How should API contracts be designed for different clients, including web, mobile, and external integrations, and what are the trade-offs between a universal API and client-specific endpoints?

How should core REST API resources be modeled: identifiers, relationships, lifecycle, and avoiding leakage of internal DB structure?

How should resource identifiers be chosen, including auto-increment IDs, UUIDs, ULIDs, and the trade-offs between readability, security, and index performance?

How should nested resources be designed in REST APIs, including /users/{id}/orders, independent collections, and the problem of duplicate paths for the same entity?

How to design nested resources such as /users/{id}/orders, when to keep independent collections, and how to avoid duplicate paths for the same entity.

How should many-to-many relationships be designed in REST APIs, including linking resources, nested endpoints, and the limitations of updating relationships?

How should aggregated resources be designed in REST APIs, including summary fields, computed values, denormalized responses, and the risk of data inconsistency?

How to design include/expand mechanisms in REST APIs to load related entities, prevent N+1 queries, and avoid problems caused by overly flexible queries.

How should include or expand mechanisms be designed in REST APIs, including loading related entities, preventing N+1 queries, and the limitations of overly flexible queries?

How should DTOs be designed for REST APIs, including separating API models from database entities, protecting internal fields, and the cost of additional mapping?

How should partial responses be designed in REST APIs, including client-selected fields, traffic reduction, and the problems this creates for caching and field-level authorization?

How should PATCH requests be designed in REST APIs, including JSON Merge Patch, JSON Patch, partial field updates, and problems with null values?

How should REST APIs be versioned, including versioning in the URL, versioning in headers, media type versioning, and trade-offs for public and internal APIs?

How should bulk operations be designed in REST APIs: mass creation, mass updates, mass deletion, and handling partial success within a single operation?

How should feature rollout be designed in REST APIs, including feature flags, gradual rollout, canary clients, and compatibility issues between backend and frontend versions?

How should deprecated REST API endpoints be safely removed, including usage monitoring, client notification, grace periods, and the risk of silent breakage?

How should backward compatibility be maintained in REST APIs, including additive changes, deprecation policies, migration windows, and the problems caused by clients that update rarely?

How should different versions of mobile clients be handled in REST APIs, including long application lifecycles, forced updates, and the cost of supporting old contracts?

How should resource states be designed in REST APIs, including draft, active, archived, deleted, and the limitations of transitions between states?

How should authentication be designed in REST APIs, including session cookies, bearer tokens, JWTs, and trade-offs between statelessness and session manageability?

How should authorization be designed in REST APIs, including role-based access control, attribute-based access control, ownership checks, and the problem of validating permissions for every resource?

How should JWTs be used safely in REST APIs, including token lifetime, refresh tokens, token revocation, and client-side token storage problems?

How should rate limiting be designed for REST APIs, including limits by user, IP address, API key, endpoint, and fair distribution between clients?

How should REST APIs be protected against brute force and credential stuffing, including throttling, account lockout, captcha, risk-based checks, and trade-offs with user experience?

How to protect REST APIs from Cross-Site Request Forgery (CSRF): differences between cookie-based auth and bearer tokens, role of SameSite cookies, and why frontend-only defenses are insufficient.

How to protect REST APIs from XSS-related risks: token storage, data sanitization, output encoding, and handling client-side compromises.

How to configure CORS for REST APIs: allowed origins, credentials, preflight requests, and risks of unsafe wildcard configurations.

How should REST APIs be protected against mass assignment, including field whitelisting, DTO validation, and the problem of mapping request bodies directly into ORM entities?

How should API keys be designed for external integrations, including scopes, rotation, expiration, audit trails, and the problem of key leakage on the client side?

How should access to sensitive data be restricted in REST APIs, including field-level authorization, masking, audit logging, and the risk of accidental personal data exposure?

How to design caching for REST APIs: principles, headers to use, CDN interaction, and handling of personalized responses.

How should sorting be designed in REST APIs to be stable, performant and deterministic across pages?

How should pagination be designed in REST APIs, including offset pagination, cursor pagination, keyset pagination, and trade-offs for large datasets?

How should ETag be used in REST APIs, including conditional GET requests, optimistic concurrency control, and the limitations of generating ETags for aggregated resources?

How should filtering be designed in REST APIs, including query parameters, ranges, full-text search, and the limitations of overly flexible query languages?

Overview: N+1 occurs when an API handler issues one query to fetch N parent rows then issues N additional queries to fetch related data. That pattern kills performance at scale. This card summarizes common prevention techniques: eager loading, batching endpoints, DataLoader-style request-level batching/caching, and how include/expand options affect performance.

Designing response compression in REST APIs: when and how to use gzip/Brotli, size thresholds, and trade-offs between CPU usage and network traffic.

How should resource creation be designed in REST APIs, including transactions, validation, side effects, and the problem of partially completed operations?

How should APIs for large file uploads be designed, including multipart uploads, resumable uploads, pre-signed URLs, and the limitations of sending files through the main backend?

How should REST APIs be optimized for mobile clients, including latency, response size, unstable networks, and the problems caused by overly granular endpoints?

How to design optimistic locking in REST APIs using version fields, ETags, If-Match headers, and how to behave on concurrent-update conflicts.

How to design download endpoints in REST APIs: streaming, range requests, access control, and memory considerations when serving large files.

How should repeated POST requests be handled in REST APIs, including idempotency keys, retry logic, duplicate detection, and the problem of network timeouts after successful operations?

How should eventual consistency be designed in REST APIs: handling asynchronous processing, delayed reads, status endpoints, and managing user expectations?

How should REST endpoint boundaries be chosen in a backend-for-frontend (BFF) architecture, considering client-specific needs, data aggregation, and the risk of duplicated business logic?

How to design REST APIs in a microservices architecture covering data ownership, API gateways, service boundaries and the distributed monolith problem.

How to provide read-after-write consistency in REST APIs: patterns, practical techniques (primary reads, cache invalidation, sticky sessions) and performance trade-offs.

How should REST APIs be designed on top of distributed transactions, including the saga pattern, outbox pattern, compensating actions, and rollback problems across services?

How should a REST API gateway be designed, including authentication, routing, rate limiting, request transformation, and the limitations of centralized gateway logic?

How should asynchronous operations be designed in REST APIs: 202 Accepted, job resources, polling, callbacks (webhooks), and why long-running work should not usually run inside a single HTTP request?

How should REST APIs for external partners be designed, including contract stability, quotas, audit logs, sandbox environments, and the difficulties of supporting third-party integrations?

How should 409 Conflict be handled in REST APIs, covering concurrent updates, unique constraints, business-rule conflicts, and client retry expectations?

Compare REST and gRPC across performance, strict contracts, browser support, streaming, and suitability for external integrations.

How should the choice between REST API and message queues be made, including latency, reliability, backpressure, retry semantics, and requirements for synchronous client responses?

How to design REST APIs that coexist with an event-driven architecture: commands over HTTP, events through a broker, eventual consistency, and a clear separation of synchronous and asynchronous communication.

How should the choice between REST API and GraphQL be made, including client control over data, caching, public integrations, and schema maintenance complexity?

How should webhook integrations be designed alongside REST APIs, including delivery guarantees, retries, signatures, idempotency, and event ordering problems?

How should distributed tracing be designed for REST APIs, including trace ID propagation, spans across services, correlated logs, and limitations in asynchronous processes?

How should logging be designed for REST APIs, including request IDs, user IDs, endpoints, latency, error codes, and handling sensitive data?

Which metrics should be selected for REST APIs: RPS, latency percentiles, error rate, saturation, and why averages can be misleading compared to p95/p99?

How to investigate REST API incidents: reconstruct timeline, identify affected endpoints, determine root cause, apply mitigations, and prevent recurrence.

How should alerting be designed for REST APIs, including SLOs, error budgets, latency alerts, and the problem of noisy alerts without clear user impact?

How should health checks be designed for REST APIs — liveness, readiness, dependency checks, and how to avoid incorrectly removing a service from the load balancer?

How should audit trails be designed for REST APIs to record who did something, which resource was affected, when it happened, what the result was, and what storage/retention rules apply in regulated systems?

How should REST APIs be tested at unit, integration, and end-to-end levels, including the boundaries of each test type, test data, and the problem of fragile E2E scenarios?

How should test environments be designed for REST APIs, including staging, sandbox, mock services, test data isolation, and differences from production behavior?

How to design graceful shutdown so APIs finish active requests, deregister from the load balancer, set sensible timeouts, and reduce the risk of losing in‑flight operations?

How to test REST API security: focus on authorization bypass, injection, rate limiting and improving negative-scenario coverage.

How should REST API load testing be performed, including RPS, latency, concurrency, realistic traffic profiles, and the problem of testing without downstream dependencies?

How to design a robust REST API for order placement: order creation, inventory reservation, payment, idempotency, and handling partially completed workflows.

How should contract testing be used for REST APIs, including consumer-driven contracts, provider verification, and the problem of misalignment between teams?

How to design a REST API for payments that handles idempotent client retries, clear transaction status, provider webhooks, and minimizes the risk of duplicate charges during network failures.

How should REST APIs be tested for resilience to dependency failures, including timeouts, retries, circuit breakers, fallbacks, and the risk of retry storms?

How to design a REST API for importing data with file upload, asynchronous processing, error reports, and handling partially valid records.

How should a REST API for user notifications be designed, including event creation, delivery through multiple channels, delivery status, and the limitations of synchronous sending?

How should a REST API for comments be designed, including nesting, moderation, soft deletion, sorting, and the limitations of deeply nested tree structures?

How to design a system that provides real-time status updates: compare polling, long polling, Server-Sent Events (SSE), WebSocket, and the limits of a pure REST approach.

How to design a REST API for product search that supports filters, sorting, facets, pagination and performs well on large catalogs?

How should a REST API for access management be designed, including roles, permissions, inheritance, ownership, and the problem of caching user permissions?

What problems arise when passing complex state through query parameters?

What problems arise when POST is used for all REST API operations?

What problems arise when REST APIs are designed around verbs instead of resources, including inconsistent modeling, documentation complexity, and endpoint proliferation?

How should a REST API for an admin panel be designed, including filtering, action auditing, bulk operations, and the risks of overly powerful endpoints?

How should a REST API for multi-tenant SaaS be designed, including tenant isolation, tenant-aware authorization, rate limits, and the risk of data leakage between tenants?

What problems arise when REST APIs return 200 OK even for errors (validation failures, auth errors, server faults)?

What problems arise when POST is used for all REST API operations?

What problems arise when REST endpoints are too fine-grained, causing chatty APIs, high latency, unnecessary round trips, and poor mobile user experience?

What problems arise when a database schema is exposed directly through REST APIs?

What problems arise when REST endpoints are too large, including overfetching, authorization complexity, weak reusability, and increased coupling between client and server?

What problems arise when pagination and filtering have no limits, including database overload, denial-of-service risks, and unpredictable latency?

What problems arise when REST APIs do not have consistent error rules, including inconsistent response bodies, complex SDKs, and worse developer experience?

What problems arise when authorization business logic is split between frontend and backend, including bypass risks, duplicated rules, and audit complexity?

How to evaluate REST API quality during an architecture review: a practical checklist covering resource model clarity, contract stability, security, observability and operational risks.

How should a REST API be designed for zero-downtime deployment, including backward-compatible migrations, the expand-and-contract pattern, and rolling update risks?

How should a public REST API for thousands of external clients be designed, including versioning, rate limits, documentation, SDKs, and long-term compatibility?

How should the decision to introduce a new REST endpoint be made, including the existing resource model, client needs, support for old clients, and maintenance cost?

How should a REST API for a high-load service be designed, including load balancing, caching, read replicas, backpressure, and graceful degradation under peak traffic?

How should a REST API for a multi-region system be designed, including latency, data residency, replication lag, and consistency problems across regions?

How to evaluate trade-offs between a simple REST API and giving clients more flexible querying (to avoid overfetching/underfetching), while considering caching and backend complexity.

When is REST no longer a good fit? Signs, requirements and practical alternatives for real-time, streaming, graph queries, low-latency S2S and architectural choices.