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.

HardTechnical

83 practiced

You need to evolve widely-used API response schemas by adding fields and restructuring nested objects. Describe strategies to maintain backward compatibility including additive changes, version negotiation, server-side defaults, feature flags, consumer migration windows, and automated backward compatibility checks. Explain how to roll out and deprecate changes safely without breaking clients.

Sample Answer

**Situation & goal**As a full‑stack developer I need to evolve widely used API response schemas without breaking clients. My strategy prioritizes additive changes, predictable defaults, and gradual rollouts with automated safety checks.

**Strategies**- **Additive changes first** - Add new top‑level fields and optional nested fields; never remove or rename existing fields. - Use nullable or optional types and document defaults.- **Version negotiation** - Support Accept / Content‑Type versioning or header like X-API-Version. - Default to v1 behavior when client omits version.- **Server-side defaults** - Serve sensible defaults for new fields so old clients ignore them. - Keep contract: existing fields’ types and semantics stay stable.- **Feature flags & runtime gating** - Gate structural changes behind feature flags per client or percentage rollout. - Use flags to A/B test and quickly roll back.- **Consumer migration window** - Announce changes, provide migration guides and client libraries. - Maintain compatibility for a defined window (e.g., 6 months) before deprecation.- **Automated backward-compatibility checks** - CI checks: validate schema changes against saved “consumer expectations” (contract tests, Pact, JSON Schema diff). - Run integration tests against representative old clients and generators.

**Rollout & deprecation plan**1. Introduce additive fields + schema docs + client library update.2. Enable behind feature flag for 1% → 10% → 100% with monitoring (errors, latency, client parsing failures).3. Run contract tests and consumer CI; notify integrators and provide migration examples.4. After migration window, mark fields deprecated in docs and start removing only after confirming no consumers use them; remove behind major-version bump with prior warning.

**Examples & best practices**- Provide JSON Schema examples and a small migration snippet for JS clients showing optional chaining and fallback values.- Maintain CHANGELOG, automated telemetry to detect client failures, and rollback plan via feature flags or previous API version.

This approach minimizes client disruption while enabling safe evolution.

EasyTechnical

117 practiced

Explain the benefits of using OpenAPI to describe and document REST APIs. Describe what elements should be included in the contract such as endpoints, request and response schemas, status codes, examples, and security schemes. Outline how to incorporate OpenAPI into CI for contract-driven development and automated docs generation.

Sample Answer

**Benefits of OpenAPI (from a Full‑Stack perspective)**- Single source of truth for frontend and backend: drives client code generation (TypeScript/React hooks) and server scaffolds.- Improves discoverability and developer onboarding with interactive docs (Swagger UI/Redoc).- Enables automated validation, contract tests and tooling (mock servers, linting).- Speeds integration and reduces miscommunication between teams.

**Essential contract elements**- Endpoints & HTTP methods (path, verb) — clear resource model.- Request schemas (query/path/header/body) and response schemas (JSON models) using JSON Schema.- Status codes mapped to responses (200/201/400/404/500) with descriptions.- Examples and sample payloads for common flows and error cases.- Security schemes (OAuth2, API keys, bearer JWT) and scopes.- Metadata: version, servers, tags, deprecation notes.

**CI / Contract-driven workflow**- Validate spec on every PR: use openapi-cli/swagger-cli or Spectral to lint/validate.- Generate server stubs and client SDKs as part of build to detect drift.- Run contract tests: generate mocks (Prism) and run integration tests against them.- Auto publish docs/artifacts: on merge build, generate Swagger UI/Redoc and deploy to docs site.

Example CI snippets:

yaml

# GitHub Actions fragment
steps:
- uses: actions/checkout@v3
- run: npm ci
- run: npx @stoplight/spectral lint api/openapi.yaml
- run: npx openapi-generator-cli generate -i api/openapi.yaml -g typescript-fetch -o client
- run: npm test
- run: npm run deploy-docs

I use OpenAPI to keep frontend types, mocks, and backend contract in sync — catching regressions early and making iterations faster.

HardTechnical

65 practiced

For a client-driven analytics dashboard that requires many nested resources and selective fields, compare REST and GraphQL. Discuss network efficiency, client control, server complexity, caching challenges, rate limiting, authorization granularity, and developer experience. Recommend when switching to GraphQL is justified and when REST might remain preferable.

Sample Answer

**Situation & summary**For a client-driven analytics dashboard with deep nested resources and need for selective fields, both REST and GraphQL are viable. Below I compare them across the requested dimensions and give a recommendation.

**Network efficiency & client control**- GraphQL: Single request can fetch nested resources and only requested fields — dramatically reduces over-/under-fetching and number of round-trips (good for dashboards with complex panels).- REST: Multiple endpoints and round-trips or custom endpoints per view; can lead to payload bloat unless you version many tailored endpoints.

**Server complexity**- GraphQL: Higher initial complexity — schema design, resolvers, batching (DataLoader), N+1 query mitigation, and query validation.- REST: Simpler server model; endpoints map directly to controllers and DB queries.

**Caching challenges**- GraphQL: Harder to cache at HTTP layer because POSTs and dynamic queries; requires client-side normalized cache (Apollo) or server-level persisted queries and cache keys.- REST: Easier HTTP caching (cache-control, etags) per resource/URL.

**Rate limiting**- GraphQL: Need query complexity/depth limits and persisted queries to avoid heavy single-request abuse.- REST: Standard per-endpoint rate limits are straightforward.

**Authorization granularity**- GraphQL: Fine-grained field-level auth possible but requires careful resolver-level checks.- REST: Role-based endpoint-level checks are simpler but coarser.

**Developer experience**- GraphQL: Great DX for front-end — self-documenting schema, introspection, single contract.- REST: Familiar, simpler debugging with standard HTTP semantics.

**Recommendation**Switch to GraphQL when: dashboard has many nested joins, frequent UI-driven field changes, mobile/latency-sensitive clients, and you can invest in server tooling (DataLoader, persisted queries, field auth). Keep REST when: needs simple caching, strict HTTP-level caching/rate-limits, team prefers lower backend complexity, or analytics mostly read-only with stable aggregated endpoints.

MediumTechnical

78 practiced

Outline a contract testing strategy for REST APIs consumed by multiple teams. Compare approaches such as provider-driven tests, consumer-driven contracts like Pact, and schema validation with OpenAPI. Describe where tests should run in CI, how to use mock servers for frontend development, and how to fail builds on breaking contract changes.

Sample Answer

**Strategy overview**- Blend approaches: use consumer-driven contracts (Pact) for fast cross-team guarantees, provider-driven tests for provider-side integration checks, and OpenAPI schema validation for surface-level, language-agnostic verification.

**Why each approach**- Consumer-driven (Pact): captures consumer expectations as executable contracts; great when many frontends/mobile apps rely on one API.- Provider-driven tests: provider writes integration tests ensuring implementation meets behavior (edge cases, side effects).- OpenAPI schema: validates request/response shapes and auto-generates mocks/docs; good baseline for backward-compatible changes.

**Test placement in CI**- Consumer CI: publish Pact contracts to a broker after consumer tests pass; run contract verification against provider’s deployed test instance (staging) or provider CI via broker webhook.- Provider CI: on PR, fetch published consumer contracts and run Pact verification suite before merge; also run OpenAPI schema validation and provider unit/integration tests.- Gate merge: if provider verification fails, block merge.

**Mock servers for frontend dev**- Generate mocks from OpenAPI for fast local dev (e.g., Prism) or run Pact mock servers created from consumer tests so frontends can develop against realistic interactions.- Provide npm script or Docker compose to run mock server with canned scenarios and feature flags.

**Failing builds on breaking changes**- Configure Pact Broker with versioning and CI pipelines: consumer publishes contract -> provider CI verifies -> if mismatch, fail build and post clear error with diff.- Enforce semantic versioning on OpenAPI (major bump for breaking changes) and run a schema-diff tool in CI (e.g., openapi-diff); fail PR when major-breaking diffs detected.- Require consumer-driven contract acceptance or explicit provider-side deprecation plan (feature flags, compatibility layer) before merging breaking changes.

**Operational practices**- Keep contracts small and example-rich.- Automate publishing/verifying with CI (GitHub Actions/GitLab).- Maintain a contract ownership doc and retro on failures to reduce churn.

EasyTechnical

83 practiced

Explain idempotency for RESTful APIs. Provide concrete examples of idempotent and non-idempotent operations, describe how to implement idempotency keys for create operations in a distributed system, and outline server-side strategies to deduplicate retried requests safely.

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.