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

73 practiced

Discuss PATCH semantics in REST. Compare JSON Merge Patch vs JSON Patch (RFC 7396 vs RFC 6902) and explain when to choose each. Describe server-side validation, partial updates, and how to handle fields that should be unset versus set to null. Include concurrency considerations with conditional headers.

Sample Answer

**Approach / summary**PATCH semantics: PATCH is for partial updates; it must be applied atomically (server decides merge semantics) and should be idempotent only if documented. Choose representation (JSON Merge Patch RFC 7396 or JSON Patch RFC 6902) based on expressiveness and simplicity.

**JSON Merge Patch (RFC 7396)**- Format: a JSON document describing the desired field-level changes; absent fields are unchanged, fields set to null are removed.- Best when: simple object updates, client sends a partial object, human-readable, easy to implement.- Example: { "name": "Alice", "phone": null } — sets name, removes phone.

**JSON Patch (RFC 6902)**- Format: array of operations: add/remove/replace/move/copy/test.- Best when: fine-grained operations, arrays/indexed edits, transactional multi-op sequences, need to assert state with "test".- Example: [ { "op":"replace","path":"/name","value":"Alice" }, { "op":"remove","path":"/phones/1" } ]

**When to choose**- Use Merge Patch for CRUD-like partial updates on flat/mostly-object resources.- Use JSON Patch when you need array-index operations, reordering, or to include server-side "test" operations for concurrency.

**Server-side validation & partial updates**1. Validate incoming patch against a schema and business rules before applying.2. For Merge Patch: deserialize, apply merge to a copy of stored resource, run validation, then persist.3. For JSON Patch: execute operations against an in-memory representation (honor "test" ops first), validate final state.4. Always sanitize fields clients shouldn’t change (immutable IDs, audit fields) and reject attempts.

**Unset vs set-to-null**- Explicitly document semantics: - In RFC 7396, null == remove/unset. - In RFC 6902, use "remove" op to unset; "replace" with null sets to null value.- If your domain distinguishes "absent" vs "null", prefer JSON Patch so you can use remove vs replace. For Merge Patch, consider using a wrapper convention (e.g., {"field": {"__op":"unset"}}) but that breaks standards.

**Concurrency**- Use conditional headers: require clients to supply If-Match: "<etag>" (strong ETag) to avoid lost updates. For JSON Patch include a "test" op as additional protection.- Flow: 1. Client GET resource + ETag. 2. Client PATCH with If-Match: ETag. 3. Server compares ETag; on mismatch return 412 Precondition Failed.- For high-concurrency, consider optimistic locking at DB level (version column) and apply patch within a transaction; retry on conflict.

**Practical tips**- Log patches for audit and replayability.- Limit patch size and rate; validate depth to avoid DoS.- Prefer JSON Patch when clients need deterministic operations; prefer Merge Patch for simplicity and bandwidth.

EasyTechnical

83 practiced

Explain HTTP caching fundamentals for APIs: Cache-Control directives, ETag, Last-Modified, and Vary. Give an example Cache-Control header value for a public read-heavy endpoint and explain how conditional requests with ETag reduce load on origin servers.

HardTechnical

73 practiced

Explain how you would implement conditional GET requests using ETags and Last-Modified in an Express or Spring backend backed by PostgreSQL. Provide the sequence of headers exchanged on both cache-hit and cache-miss, and outline how you would generate and validate ETag values efficiently for large, frequently changing resources.

Sample Answer

**Approach (brief)**

Use Last-Modified (from a row's updated_at) and ETag (strong or weak) to let clients send If-Modified-Since / If-None-Match. On conditional GET: validate server-side; return 304 when unchanged; otherwise 200 with new body and headers.

**Sequence of headers**

- Cache miss (first GET): - Request: none - Response: 200 OK - Last-Modified: Tue, 02 Mar 2026 12:34:56 GMT - ETag: "v12345" (or weak: W/"hash") - Cache-Control: public, max-age=60

- Cache hit (client conditional): - Request: If-Modified-Since: Tue, 02 Mar 2026 12:34:56 GMT If-None-Match: "v12345" - Response if unchanged: 304 Not Modified - ETag: "v12345" - (no body) - Response if changed: 200 OK (new body + updated Last-Modified, ETag)

**Express example (Node.js)**

javascript

// Express pseudo-code
app.get('/resource/:id', async (req,res)=>{
  const row = await db.query('select data, updated_at, version from items where id=$1', [req.params.id]);
  const last = row.updated_at.toUTCString();
  const etag = `"${row.version}"`; // cheap surrogate
  res.set('Last-Modified', last);
  res.set('ETag', etag);
  if (req.headers['if-none-match'] === etag || new Date(req.headers['if-modified-since']) >= row.updated_at) {
    return res.status(304).end();
  }
  res.json(row.data);
});

**Spring (Java) sketch**

java

@GetMapping("/resource/{id}")
public ResponseEntity<?> get(...) {
  Row r = repo.findById(id);
  String etag = "\""+r.getVersion()+"\"";
  HttpHeaders h = new HttpHeaders();
  h.setETag(etag);
  h.setLastModified(r.getUpdatedAt().toEpochMilli());
  if (request.checkNotModified(etag)) return new ResponseEntity<>(h, HttpStatus.NOT_MODIFIED);
  return ResponseEntity.ok().headers(h).body(r.getData());
}

**Efficient ETag generation for large, frequently-changing resources**

- Avoid full-content hashing on every request. Use: - Incrementing version column (Postgres bigserial or integer) updated in same transaction as content change — O(1) to read. - Last-updated timestamp (updated_at) for Last-Modified and weak ETag semantics. - Content-hash precompute on write only (trigger or app-level) stored in DB if you need strong ETags. - For composed resources, maintain a lightweight "aggregate_version" that changes when any part changes (materialized view or join-triggered update).- Trade-offs: - Version column: fastest, supports strong equality if updated deterministically. - Hash-on-write: accurate strong ETag, more storage but avoids read-time CPU. - Weak ETag (W/..): useful when byte-for-byte equality isn't required.

**Validation rules & best practices**

- Prefer If-None-Match over If-Modified-Since when both provided (RFC7232).- Ensure ETag and Last-Modified updated in same DB transaction to avoid races.- Use Cache-Control and Vary where appropriate.- Monitor hit-rate and tune max-age vs validation frequency.

MediumSystem Design

59 practiced

You maintain a microservices architecture where the API Gateway terminates authentication. Discuss the trade-offs of performing authorization checks at the gateway layer versus deferring to each downstream service. Include considerations for least privilege, latency, complexity, and maintaining a central policy.

Sample Answer

**Clarify trade-offs (high level)**

- API Gateway authorization (centralized): enforces coarse-grained rules (routes, scopes, roles) as requests enter the system.- Downstream service authorization (decentralized): services enforce fine-grained, resource-specific rules (owner checks, business rules).

**Least privilege**- Gateway: good for broad access control (deny by default, role/scope checks). But it can’t enforce resource-level constraints (user X can read only their invoices).- Services: can check resource ownership/attributes; therefore stronger least-privilege guarantees for business-sensitive data. Recommended: gateway for coarse gates + services for fine-grained checks.

**Latency**- Gateway-only: lowest end-to-end latency if all decisions done once, but may be over-permissive.- Service checks: extra round-trips to policy evaluation or DB lookups increase latency. Mitigations: local policy caches, tokenized claims (JWT with scopes/claims), lightweight policy engine libraries embedded in service.

**Complexity**- Centralized: simpler to audit and maintain common rules; fewer places to update. But complex business rules become hard to express and maintain in gateway, and rule explosion can occur.- Decentralized: each service must implement/maintain policies—risk of inconsistent enforcement and duplication. Use shared libraries or a policy-as-code approach to reduce drift.

**Maintaining a central policy**- Use a central policy repository and engine (e.g., OPA or a policy service) to author policies; expose them to gateway and services.- Pattern: Push common RBAC/ABAC policies to gateway; expose a policy evaluation API (or distribute compiled policies) so services can evaluate locally for low latency.

**Recommendation (practical for backend dev)**- Implement defense-in-depth: - Gateway: authentication + coarse-grained authorization (roles, scopes, rate limits). - Services: fine-grained authorization (resource ownership, business rules) using a shared policy library or OPA Rego bundles cached locally.- Use JWT claims for cheap checks, cache policy decisions, and centralize policy authoring to avoid drift. This balances least privilege, acceptable latency, manageable complexity, and a single source of truth.

EasyTechnical

80 practiced

You are designing error handling for an API. For each scenario below, pick the most appropriate HTTP status code and briefly justify your choice: a) malformed JSON in request, b) validation error for a business rule (e.g., date in past), c) authentication failure, d) authorization failure, e) resource not found, f) request accepted for asynchronous processing. Return a consistent JSON error payload example you would use.

Sample Answer

**HTTP status choices (Backend Developer perspective)**

- a) Malformed JSON in request - 400 Bad Request — client sent unreadable payload; server can't parse request body. Use this instead of 415 because content-type may be correct but body invalid.

- b) Validation error for a business rule (e.g., date in past) - 422 Unprocessable Entity — syntactically valid JSON but semantically invalid per business rules. Keeps 400 for generic client errors and distinguishes validation semantics.

- c) Authentication failure - 401 Unauthorized — credentials missing/invalid; response should include WWW-Authenticate header when appropriate.

- d) Authorization failure - 403 Forbidden — authenticated but not allowed to perform this action or access this resource.

- e) Resource not found - 404 Not Found — resource doesn't exist (avoid leaking whether it existed for security-sensitive resources).

- f) Request accepted for asynchronous processing - 202 Accepted — request accepted and will be processed asynchronously; include location or status endpoint to poll.

Example consistent JSON error payload (fields chosen for clarity and machine-readability):

json

{
  "error": {
    "code": "validation_error",
    "http_status": 422,
    "message": "Start date must be in the future",
    "details": [
      {
        "field": "start_date",
        "reason": "date_in_past",
        "message": "Provided start_date 2023-01-01 is before today"
      }
    ],
    "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "help": "https://api.example.com/docs/errors#validation_error"
  }
}

Notes: include request_id for tracing, machine-readable code for clients, and optional help link or status-location for async 202 responses.

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.