Bird
Raised Fist0

API Versioning Strategies - URL, Header, Content Negotiation

HLDmediumInterview freq: common
Choose your preparation mode4 modes available
ArchitectureTraceChallenge
🎯
API Versioning Strategies - URL, Header, Content Negotiation
45 min · senior
senior

You are designing the API versioning strategy for a 50 million daily active user (DAU) startup that provides a RESTful API to third-party developers and internal clients. The system must support multiple API versions concurrently to enable backward compatibility and smooth client migration. The API must enforce TLS encryption for all traffic, maintain a P99 latency under 200ms, and allow for flexible version negotiation without breaking existing clients. The system should also support gradual deprecation of older versions and provide clear error handling for unsupported versions.

Constraints
  • Support concurrent multiple API versions without downtime
  • All API traffic must be encrypted using TLS 1.3
  • P99 API response latency must be under 200ms at 50M DAU scale
  • Version negotiation must be flexible to support legacy and new clients
  • Clear error handling for unsupported or deprecated versions
  • Backward compatibility must be maintained during rollout
📋
Guided Steps
1/5
Step 1
Choosing the API Versioning Strategy
Which API versioning strategy (URL path, custom header, or content negotiation) best fits the startup's scale and constraints, and why?
💡 Hint
Consider client compatibility, caching, and ease of routing at scale.
Key Decision
Use URL path versioning (e.g., /v1/resource) for explicit versioning and CDN caching benefits, combined with Accept header content negotiation for flexible media-type versioning using 'application/vnd.company.v1+json'.
Interviewer Expectation
Mid-level: Names URL path versioning for simplicity. Senior: Explains CDN caching benefits with URL versioning and how Accept header enables backward-compatible media-type negotiation.
⚠️Common Wrong Answer
Using only custom headers for versioning - breaks CDN caching and increases complexity in routing at 50M DAU scale, leading to higher latency.
Step 2
Designing Version Routing and Enforcement
How will the API gateway or load balancer route requests based on versioning information, and how will unsupported versions be handled?
💡 Hint
Think about TLS termination, routing rules, and error response standards.
Key Decision
Use Envoy proxy with TLS termination to inspect URL path and Accept headers, route to version-specific backend services, and return HTTP 426 Upgrade Required or 400 Bad Request for unsupported versions.
Interviewer Expectation
Mid-level: Mentions Envoy or NGINX for routing. Senior: Details Envoy’s ability to parse headers and URL, enforce TLS 1.3, and return precise HTTP status codes for version errors.
⚠️Common Wrong Answer
Routing based on query parameters - query params are less cache-friendly and complicate routing, increasing latency beyond 200ms P99.
Step 3
Supporting Backward Compatibility and Deprecation
How will the system support multiple versions concurrently and manage deprecation without breaking clients?
💡 Hint
Consider version lifecycle management and client notification mechanisms.
Key Decision
Implement versioned microservices behind the API gateway with feature flags and deprecation headers (e.g., 'Deprecation' and 'Sunset' HTTP headers) to notify clients; use Kafka for event-driven rollout coordination.
Interviewer Expectation
Mid-level: Describes running multiple versions simultaneously. Senior: Explains use of Kafka for rollout orchestration and HTTP headers for client-side deprecation awareness.
⚠️Common Wrong Answer
Forcing immediate version cutover - causes client breakage and spikes in error rates at 50M DAU scale.
Step 4
Ensuring Security and Performance at Scale
How will the system ensure TLS encryption and maintain P99 latency under 200ms given 50M DAU traffic?
💡 Hint
Think about TLS termination, caching, and load balancing technologies.
Key Decision
Terminate TLS 1.3 at Envoy proxies deployed in multiple regions, leverage CDN edge caching for URL versioned endpoints, and use Redis for caching authentication tokens to reduce backend load.
Interviewer Expectation
Mid-level: Mentions TLS termination and caching. Senior: Details Envoy TLS 1.3 termination benefits, CDN caching with versioned URLs, and Redis token caching to meet latency SLAs.
⚠️Common Wrong Answer
Terminating TLS at backend services - increases CPU load and latency, risking P99 SLA breaches.
Step 5
Designing Clear Error Handling for Versioning
What error responses and headers should the API return when clients request unsupported or deprecated versions?
💡 Hint
Consider HTTP status codes and standard headers for versioning errors.
Key Decision
Return HTTP 400 Bad Request for malformed version info, 404 Not Found for non-existent versions, and 426 Upgrade Required with 'Deprecation' and 'Sunset' headers for deprecated versions.
Interviewer Expectation
Mid-level: Knows basic HTTP error codes. Senior: Explains use of 426 status and standard headers to guide client upgrades and deprecation timelines.
⚠️Common Wrong Answer
Returning generic 500 errors - confuses clients and complicates debugging at scale.
🔌
API Design Challenge
Sketch 3 core endpoints illustrating how clients specify API versions using URL path, HTTP headers, and content negotiation. Include request and response examples.
Hints
  • How does the client specify the API version in the URL path?
  • What HTTP headers can be used to indicate API version?
  • How does content negotiation via Accept header enable versioning?
📊
Scoring Rubric
▼ Show
Must Have - 60%
  • Explicit versioning strategy with URL path and header negotiation
  • TLS 1.3 termination at edge proxies
  • Version-based routing with Envoy or equivalent
  • Clear error handling with appropriate HTTP status codes
  • Support for concurrent multiple API versions
Good to Have - 30%
  • Use of Kafka for rollout coordination
  • Redis caching for authentication tokens
  • Deprecation headers to notify clients
  • CDN caching leveraging versioned URLs
Bonus - 10%
  • Multi-region deployment for latency and availability
  • Detailed client notification mechanisms for version upgrades
Anti-patterns to Avoid
Using only custom headers for versioning - breaks CDN caching and increases latency due to complex routing at 50M DAU scale
Routing based on query parameters - complicates caching and routing, increasing latency and risking P99 SLA breaches
Immediate version cutover without deprecation strategy - causes client breakage and spikes in error rates at 50M DAU scale
Terminating TLS at backend services - increases CPU load and latency, risking SLA breaches and degraded performance
Returning generic 500 errors for version issues - confuses clients and complicates debugging at scale, leading to poor client experience
✅
Model Answer
▼ Reveal

The recommended API versioning strategy combines explicit URL path versioning for CDN caching and routing clarity with Accept header content negotiation for flexible media-type versioning. Envoy proxies terminate TLS 1.3 at the edge, inspect version info in URL and headers, and route requests to versioned microservices. Kafka coordinates event-driven rollout and deprecation notifications, while Redis caches authentication tokens to maintain P99 latency under 200ms at 50M DAU scale. Clear error handling uses HTTP 400, 404, and 426 status codes with 'Deprecation' and 'Sunset' headers to guide clients through version lifecycle.

Key Decisions
  • Use URL path versioning (e.g., /v1/resource) to enable CDN caching and explicit routing
  • Support Accept header content negotiation with media types like 'application/vnd.company.v1+json' for flexible version negotiation
  • Terminate TLS 1.3 at Envoy proxies deployed multi-regionally to ensure security and low latency
  • Route requests based on URL path and Accept headers using Envoy, returning HTTP 426 or 400 for unsupported versions
  • Implement versioned microservices with feature flags and use Kafka for event-driven rollout and deprecation coordination
  • Cache authentication tokens in Redis to reduce backend load and meet latency SLAs
  • Use HTTP 426 Upgrade Required with 'Deprecation' and 'Sunset' headers to notify clients of deprecated versions and guide upgrades
  • URL path versioning (e.g., /v1/resource) enables CDN caching and explicit routing
  • Accept header content negotiation with media types (e.g., application/vnd.company.v1+json) supports flexible versioning
  • Envoy proxy for TLS 1.3 termination, header inspection, and version-based routing
  • Kafka for event-driven coordination of version rollout and deprecation notifications
  • Redis caching of authentication tokens to reduce backend load and maintain P99 latency < 200ms
  • HTTP 426 Upgrade Required and standard 'Deprecation'/'Sunset' headers for clear client version deprecation signaling
  • Multi-region Envoy deployment with CDN edge caching to handle 50M DAU scale securely and efficiently
  • Versioned microservices architecture to isolate changes and enable backward compatibility

Practice

(1/5)
1. A CDN caches content globally and needs to automatically remove stale content after a fixed duration without manual intervention. Which cache invalidation strategy best fits this requirement?
easy
A. Time-To-Live (TTL) expiration set on cached objects
B. Surrogate keys to selectively invalidate groups of content
C. Manual purge triggered by an admin when content updates
D. Client-side cache control headers only

Solution

  1. Step 1: Identify automatic expiration mechanism

    TTL automatically expires cached content after a set time without manual action.

  2. Step 2: Eliminate manual and selective invalidation

    Manual purge requires human action; surrogate keys target groups, not time-based expiry; client-side headers don't enforce server cache expiry.

  3. Final Answer:

    Option A -> Option A

  4. Quick Check:

    TTL auto-expires stale cache entries without manual purge [check]
Hint: TTL auto-expires cache after set time [check]
Common Mistakes:
2. If the Kafka broker cluster loses ZooKeeper coordination, what exactly breaks in the message delivery process?
medium
A. Messages are lost immediately as brokers cannot write to logs
B. Producers can still write, but partition leadership cannot be elected, causing delivery stalls
C. Consumers receive duplicate messages due to offset corruption
D. The entire cluster shuts down automatically to prevent data loss

Solution

  1. Step 1: Role of ZooKeeper in Kafka

    ZooKeeper manages partition leadership and consumer offsets; losing it affects coordination but not immediate message loss.

  2. Step 2: Failure impact on delivery

    Without ZooKeeper, offset metadata can become inconsistent, causing consumers to re-read messages and receive duplicates (C); producers may still write (B is partially true but leadership election stalls eventually); cluster does not shut down automatically (D).

  3. Final Answer:

    Option C -> Option C

  4. Quick Check:

    ZooKeeper loss -> offset inconsistency -> duplicate consumer messages [check]
Hint: ZooKeeper loss corrupts offsets causing duplicates, not immediate loss [check]
Common Mistakes:
3. For a high-traffic API, which approach better captures user experience degradation under load: reporting average latency or reporting P95 latency, and why?
medium
A. P95 latency, because it highlights the slowest 5% of requests affecting users
B. Average latency, because it is easier to compute in real-time
C. Average latency, because it summarizes all requests evenly
D. P95 latency, because it ignores outliers and focuses on median performance

Solution

  1. Step 1: Understand average latency limitations

    Average latency can be skewed by many fast requests and hide slow request impact, thus missing user experience degradation.

  2. Step 2: Why P95 latency is better

    P95 latency captures the slowest 5% of requests, which often cause user frustration and indicate performance issues under load.

  3. Final Answer:

    Option A -> Option A

  4. Quick Check:

    P95 latency reveals slow requests impacting users better than average [check]
Hint: P95 reveals slow requests; average hides tail latency [OK]
Common Mistakes:
4. You must design a REST API for a resource that supports partial updates. Which approach best balances client flexibility and server complexity?
medium
A. Use HTTP PUT with the full resource representation for every update
B. Use HTTP PATCH with JSON Patch format for partial updates
C. Use HTTP POST to a custom /update endpoint with partial data
D. Use HTTP PUT with query parameters specifying fields to update

Solution

  1. Step 1: Compare HTTP methods for partial updates

    PUT requires full resource; PATCH supports partial updates natively.

  2. Step 2: Evaluate JSON Patch benefits

    JSON Patch is a standardized format allowing precise partial modifications, reducing payload size and server logic.

  3. Final Answer:

    Option B -> Option B

  4. Quick Check:

    PATCH with JSON Patch enables flexible partial updates [check]
Hint: PATCH + JSON Patch = flexible partial updates [check]
Common Mistakes:
5. At 10x transaction volume, which component in the digital wallet system is most likely to become the first bottleneck, and why?
hard
A. The event log (Kafka), because partition count limits throughput and rebalancing partitions causes downtime
B. The reconciliation service, because it performs expensive cross-checks on all transactions synchronously
C. The API gateway, because it handles all client requests and cannot horizontally scale due to session affinity
D. The ledger database, because it requires strong consistency and cannot shard entries without breaking double-entry guarantees

Solution

  1. Step 1: Analyze ledger database constraints

    Ledger DB enforces strong consistency and atomic double-entry transactions, limiting sharding options.

  2. Step 2: Compare other components

    Reconciliation (A) can be scaled asynchronously; API gateway (C) can be scaled with stateless design; Kafka (D) scales with partitioning but ledger DB consistency is harder to scale.

  3. Final Answer:

    Option D -> Option D

  4. Quick Check:

    Ledger DB consistency limits sharding -> first bottleneck [check]
Hint: Ledger DB consistency limits sharding -> first bottleneck [OK]
Common Mistakes:
Recommended

Ready to prove it?

Pass the test and this pattern moves unknown strong while earning +1 Grip toward your certificate.

10 questions~5 mineasy hard