This chapter covers API versioning strategies, a critical topic for the DVA-C02 exam as it directly impacts how developers manage breaking changes in serverless and API-based architectures. Understanding versioning is essential for designing APIs that evolve without disrupting existing clients. Approximately 5-10% of exam questions touch on API versioning, often in scenarios involving API Gateway, Lambda, or microservices. You will learn the key strategies—URI path, query parameter, header-based, and custom header—along with their trade-offs, best practices, and common exam traps.
Jump to a section
Imagine a restaurant that updates its menu every season. In version 1.0, the menu lists 'Grilled Salmon' with a lemon butter sauce. In version 2.0, the restaurant changes the recipe to a dill cream sauce but keeps the same name. A customer who loved the old lemon butter sauce orders 'Grilled Salmon' expecting the old recipe, but receives the new dill cream sauce. This creates confusion and dissatisfaction. To avoid this, the restaurant adopts a versioning strategy: each menu is clearly labeled as 'Menu v1.0' and 'Menu v2.0', and customers must specify which version they want. Alternatively, the restaurant could maintain both versions indefinitely, or require customers to use a new ordering system for the updated menu. In API versioning, the restaurant is the API provider, the menu is the API contract, and the customers are client applications. The challenge is to introduce changes without breaking existing clients. The versioning strategy—URI path, query parameter, header, or custom header—determines how clients specify which version they want. Just as a restaurant might phase out old menus over time, API providers deprecate old versions with a timeline and migration guide. The analogy breaks down when considering backward compatibility: unlike a restaurant that can always make both recipes, API providers often cannot maintain infinite versions due to cost and complexity. The core lesson is that versioning is about managing change and communication between provider and consumer.
What Is API Versioning and Why Does It Exist?
API versioning is the practice of managing changes to an API over time by assigning version identifiers to different states of the API contract. The primary goal is to allow the API provider to evolve the API—adding new features, changing behavior, or removing deprecated functionality—without breaking existing client applications. Without versioning, a single change could cause all clients to fail, leading to downtime and frustrated users.
How It Works: The Core Mechanism
API versioning works by associating a version identifier with each request or response, enabling the server to route the request to the appropriate implementation. The version identifier can be placed in different parts of the HTTP request:
URI Path: e.g., /v1/users, /v2/users
Query Parameter: e.g., /users?version=1
Custom Request Header: e.g., Accept: application/vnd.myapi.v1+json
Custom Header (e.g., X-API-Version): e.g., X-API-Version: 1
Host Header: e.g., v1.api.example.com
Each strategy has implications for caching, discoverability, routing, and client complexity.
Key Strategies and Their Trade-offs
#### 1. URI Path Versioning (Most Common)
How it works: The version is part of the URL path, e.g., https://api.example.com/v1/users.
Advantages:
Highly visible and easy to understand.
Simple to implement in API Gateway using path-based routing.
Works well with HTTP caching (cache keys include the version).
Easy to test and debug.
Disadvantages:
Clutters the URL and can be seen as less RESTful (some argue the URL should represent a resource, not a version).
Forces clients to change URLs when version changes.
Can lead to duplication of code if not managed properly.
Exam tip: API Gateway supports this natively by creating separate resources or using a {version} path parameter and mapping to different Lambda functions.
#### 2. Query Parameter Versioning
How it works: The version is passed as a query parameter, e.g., https://api.example.com/users?version=1.
Advantages:
Keeps URLs clean and resource-focused.
Easy to implement without changing routing logic.
Disadvantages:
Version is not part of the cache key by default (unless explicitly included).
Can be easily omitted by mistake, leading to default version ambiguity.
Less discoverable than path-based versioning.
Exam tip: The exam often tests the caching implication: query parameters are part of the cache key if the API Gateway is configured to do so, but by default, API Gateway does not include query strings in cache keys.
#### 3. Custom Request Header Versioning
How it works: Clients include a custom header like Accept: application/vnd.myapi.v1+json or X-API-Version: 1.
Advantages:
Keeps URLs clean and version-neutral.
Allows for content negotiation (e.g., different representations for different versions).
Disadvantages:
Less visible and harder to test (e.g., in a browser).
Caching can be tricky since the header is not part of the URL.
Requires client-side header injection.
Exam tip: The Accept header approach is more RESTful and is often used in hypermedia APIs. API Gateway can use header mapping to route to different integration endpoints.
#### 4. Host Header Versioning (Subdomain)
How it works: The version is in the hostname, e.g., v1.api.example.com.
Advantages:
Allows separate infrastructure per version (e.g., different API Gateway stages).
Clear separation of concerns.
Disadvantages:
Requires DNS configuration and possibly SSL certificates per subdomain.
Can be more expensive and complex.
Exam tip: This is less common on the exam but may appear as a valid option for major version changes.
Versioning Strategies in AWS API Gateway
API Gateway is the primary service for creating RESTful APIs in AWS. It supports multiple versioning approaches:
Stage-based versioning: Create different stages (e.g., v1, v2) and deploy different API versions to each stage. Clients call https://{api-id}.execute-api.{region}.amazonaws.com/v1.
Resource path versioning: Use a path parameter like {version} and map it to different Lambda functions or integration endpoints.
Custom domain names: Map a custom domain like api.example.com to a specific stage, and use different domain names per version (e.g., v1.api.example.com).
Interacting with Related Technologies
Lambda: When using API Gateway with Lambda, versioning often involves deploying different Lambda function versions or aliases (e.g., PROD alias points to version 1, V2 alias points to version 2).
DynamoDB: API versions may map to different table schemas. For example, v1 uses a flat table, v2 uses a single-table design. The API version determines which schema to use.
Cognito: If using custom headers for versioning, ensure that Cognito authorizers can pass the version header to the backend.
CloudFront: When using CloudFront in front of API Gateway, versioning via URI path works well. Header-based versioning requires CloudFront to forward the custom header.
Best Practices
Use semantic versioning (e.g., v1.0.0, v2.0.0) but only expose the major version in the API (e.g., v1, v2).
Deprecate old versions with a clear timeline (e.g., 6 months notice).
Include deprecation headers in responses (e.g., Sunset: Sat, 31 Dec 2023 23:59:59 GMT).
Document all versions and provide migration guides.
Use API Gateway usage plans to control access per version.
Common Pitfalls
Not versioning at all: Leads to breaking changes without notice.
Versioning only the URI but not the logic: All versions go to the same backend, defeating the purpose.
Forgetting to deprecate: Old versions accumulate, increasing maintenance cost.
Using query parameters without caching: Causes performance issues.
Exam-Specific Details
The exam expects you to know that URI path versioning is the most common and simplest to implement.
API Gateway charges per API call, regardless of versioning strategy.
For header-based versioning, the Accept header is more RESTful than a custom X-API-Version header.
AWS recommends using stage variables to manage version routing in API Gateway.
When using Lambda, you can use aliases to point to different function versions for different API versions.
Configuration Example: API Gateway with URI Path Versioning
Create a REST API in API Gateway.
Create a resource /v1 and a resource /v2.
For each resource, create a method (e.g., GET) and integrate with a Lambda function.
Deploy the API to a stage (e.g., prod).
Clients call https://api-id.execute-api.region.amazonaws.com/prod/v1/users.
Verification Commands
Using curl:
curl https://api-id.execute-api.region.amazonaws.com/prod/v1/usersWith header versioning:
curl -H "Accept: application/vnd.myapi.v1+json" https://api-id.execute-api.region.amazonaws.com/prod/usersSummary of Defaults and Timers
API Gateway has a maximum integration timeout of 29 seconds.
There is no default version; if not specified, the API may return a 400 Bad Request or default to the latest version (configurable).
Version deprecation should include a Sunset header with a date.
Interaction with Caching
URI path versioning: Cache key includes the full path, so different versions are cached separately.
Query parameter versioning: Cache key includes query parameters if enabled.
Header versioning: Cache key does not include headers by default; you must enable header forwarding in CloudFront or API Gateway cache.
Security Considerations
Ensure that all versions enforce the same authentication and authorization.
Do not expose internal version numbers (e.g., v1.2.3); use simple major versions.
Use API Gateway resource policies to restrict access to specific versions if needed.
Conclusion
API versioning is a fundamental skill for building evolvable APIs. The DVA-C02 exam tests your ability to choose the right strategy for a given scenario, understand the trade-offs, and implement it using AWS services like API Gateway and Lambda. Focus on URI path versioning as the default, but be prepared to justify header-based versioning for more RESTful designs.
Identify Breaking Changes
The first step is to determine if a change to the API is backward-compatible or breaking. Backward-compatible changes include adding new optional fields, adding new endpoints, or extending enumerations. Breaking changes include removing fields, changing data types, renaming endpoints, or altering authentication requirements. The API provider must assess the impact on existing clients. For example, if a 'name' field is split into 'firstName' and 'lastName', existing clients that expect a single 'name' will break. This step is critical because it dictates whether a new version is needed. The exam often presents a scenario with a change and asks if it requires a new version. The rule: if a client written for the old API would fail with the new API, it's a breaking change.
Choose a Versioning Strategy
Based on the API's requirements and client constraints, select one of the four main strategies: URI path, query parameter, custom header, or host header. URI path is the most common and is recommended for simplicity. Query parameter is easy but has caching pitfalls. Custom header is more RESTful but less visible. Host header allows separate infrastructure. The choice affects how clients call the API and how the backend routes requests. For the exam, remember that URI path versioning is the default and most straightforward. The strategy should be documented and communicated to all clients.
Implement Version Routing
In API Gateway, this involves creating separate resources or using a path parameter like {version}. For URI path versioning, create resources /v1 and /v2. For header-based versioning, use a mapping template to extract the version from the header and route to the appropriate Lambda alias. For example, create a Lambda function with two aliases: 'v1' and 'v2'. The API Gateway integration maps the version to the alias. This step requires careful configuration to ensure that each version points to the correct backend code. AWS recommends using stage variables to store the version, so you can change the mapping without redeploying the API.
Deploy and Test Versions
Deploy the API to a stage (e.g., 'prod'). Test each version independently to ensure they work as expected. For URI path versioning, test endpoints like /v1/users and /v2/users. For header-based versioning, use curl with the appropriate header. Verify that the correct backend code is invoked. Also test error handling: if a client omits the version or uses an unknown version, the API should return a 400 Bad Request or 404 Not Found. The exam may ask about default version behavior: if no version is specified, the API might default to the latest version or return an error. Best practice is to require an explicit version.
Deprecate Old Versions
After a new version is stable, announce a deprecation timeline for the old version. Use HTTP headers like 'Deprecated: true' and 'Sunset: date' in responses from the old version. Provide migration guides and support. After the sunset date, the old version can be removed or return a 410 Gone. In API Gateway, you can delete the old resources or stage. For Lambda, you can delete the old alias or function version. The exam tests the concept of deprecation headers and the importance of giving clients time to migrate. Common mistake: removing old versions too quickly without notice.
Scenario 1: E-commerce Platform with Mobile and Web Clients
A large e-commerce company provides a RESTful API for its product catalog. Initially, the API uses URI path versioning (e.g., /v1/products). After a year, they need to introduce a new pricing model that requires changing the price field from a number to an object containing amount and currency. This is a breaking change for mobile clients that parse price as a float. The company implements version 2 (/v2/products) while maintaining /v1/products for existing clients. They use API Gateway with two separate Lambda functions: one for v1 that returns the old format, and one for v2 that returns the new format. They set a deprecation date for v1 6 months out and include a Sunset header. During the transition, they monitor usage metrics to ensure clients are migrating. The main challenge is maintaining two codebases, but the cost is justified by not breaking millions of mobile users.
Scenario 2: SaaS Provider with Header-Based Versioning
A SaaS company offers a REST API for its CRM product. They use custom header versioning with the Accept header (e.g., Accept: application/vnd.crm.v1+json). This allows them to keep a clean base URL (https://api.crm.com/contacts). They chose header-based versioning because they want to support content negotiation (JSON vs XML) and versioning in a single header. They use API Gateway with a mapping template that extracts the version from the Accept header and routes to different Lambda aliases. The downside is that clients must set the header explicitly, which can be error-prone. They provide SDKs that automatically set the header. For caching, they use CloudFront with a custom cache key that includes the Accept header. This scenario highlights the trade-off between RESTful purity and ease of use.
Scenario 3: Microservices with Host Header Versioning
A financial services company uses a microservices architecture. Each microservice is independently deployable and versioned. They use host header versioning: v1.accounts.example.com, v2.accounts.example.com. This allows them to deploy different versions on separate infrastructure (e.g., different ECS services). API Gateway is not used; instead, they use Application Load Balancer (ALB) with path-based routing or host-based routing. The advantage is complete isolation: v2 can have different scaling policies and security groups. The disadvantage is cost and complexity. They manage this with infrastructure as code (CloudFormation). This approach is suitable for major version overhauls where the old version must remain untouched for compliance reasons.
The DVA-C02 exam tests API versioning primarily in the context of designing and implementing APIs with API Gateway, Lambda, and related services. The relevant objective code is Domain 1: Development with AWS Services, Objective 1.2: Develop APIs using API Gateway. Expect 2-3 questions on versioning strategies, deprecation, and best practices.
Most Common Wrong Answers: 1. 'Use query parameter versioning because it is the most secure.' (Wrong: query parameters are not inherently more secure; they are more visible and can be logged.) 2. 'Always use the latest version as the default when no version is specified.' (Wrong: best practice is to require an explicit version to avoid accidental breaking changes.) 3. 'Header-based versioning is the easiest to test in a browser.' (Wrong: headers are harder to set in a browser; URI path is easiest.) 4. 'You should version every minor change.' (Wrong: only version breaking changes; minor changes can be backward-compatible.)
Specific Numbers and Terms:
- The exam uses the terms 'breaking change' and 'backward-compatible'.
- URI path versioning is the 'most common' and 'simplest'.
- The Sunset header is used for deprecation.
- API Gateway integration timeout is 29 seconds (but not directly related to versioning).
Edge Cases: - What if a client sends a request without a version? The API should return a 400 Bad Request or default to a specific version (but the exam expects that you should not default). - How to handle versioning when using Lambda? Use aliases to point to different function versions. - Can you use stage variables for versioning? Yes, to map to different Lambda functions.
Eliminating Wrong Answers:
- If the question asks for the 'most RESTful' approach, choose Accept header versioning.
- If the question asks for the 'easiest to implement', choose URI path.
- If the question asks about caching, remember that URI path versioning naturally separates cache keys.
- If a question mentions 'content negotiation', the answer involves the Accept header.
Study Tip: Practice identifying breaking changes in sample API specifications. Know that adding an optional field is backward-compatible, but renaming a field is breaking.
URI path versioning (e.g., /v1/resource) is the most common and simplest strategy for API versioning in API Gateway.
Only breaking changes require a new major version; backward-compatible changes can be added to the existing version.
Header-based versioning using the Accept header is more RESTful and supports content negotiation.
Deprecate old versions with a Sunset header and provide a migration timeline; do not keep versions indefinitely.
API Gateway can use stage variables or separate resources to implement versioning.
When using Lambda, use aliases to point to different function versions for different API versions.
If no version is specified, best practice is to return a 400 Bad Request rather than defaulting to the latest version.
These come up on the exam all the time. Here's how to tell them apart.
URI Path Versioning
Version appears in the URL path (e.g., /v1/users).
Highly visible and easy to test in a browser.
Cache key naturally includes the version.
Simple to implement in API Gateway with separate resources.
Clients must change URL when version changes.
Header-Based Versioning
Version is in a custom header (e.g., Accept or X-API-Version).
Less visible; requires header injection.
Cache key must be configured to include the header.
More RESTful; allows content negotiation.
Clients can keep the same URL across versions.
Mistake
API versioning should be done using the URL only.
Correct
While URI path versioning is common and simple, other strategies like header-based versioning are more RESTful and can be better for certain use cases, such as content negotiation. The choice depends on requirements.
Mistake
Once you version an API, you must keep all previous versions forever.
Correct
Best practice is to deprecate old versions after a reasonable period (e.g., 6 months) and eventually remove them. Keeping infinite versions increases maintenance costs and complexity.
Mistake
Query parameter versioning is better because it keeps the URL clean.
Correct
Query parameter versioning can lead to caching issues because the version is not part of the cache key by default. Also, it is less discoverable and can be omitted accidentally.
Mistake
All changes require a new API version.
Correct
Only breaking changes require a new major version. Backward-compatible changes (adding optional fields, new endpoints) can be added to the existing version without versioning.
Mistake
API Gateway automatically handles versioning when you use stage variables.
Correct
Stage variables are a tool to help implement versioning, but you must configure the mapping yourself. API Gateway does not automatically version your API.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
There is no single 'best' strategy; it depends on your requirements. URI path versioning is the most common and simplest to implement. Header-based versioning (using the Accept header) is more RESTful and allows content negotiation. For the DVA-C02 exam, URI path versioning is often the default answer unless the question specifies a need for content negotiation or RESTful purity.
You can implement versioning by creating separate resources for each version (e.g., /v1, /v2) or by using a path parameter like {version}. For header-based versioning, use a mapping template to extract the version from the header and route to the appropriate integration. You can also use stage variables to point to different Lambda aliases. The exam expects you to know these implementation details.
Create a new major version only when you introduce breaking changes, such as removing a field, changing a data type, or altering authentication. Backward-compatible changes (adding optional fields, new endpoints) can be made without versioning. The exam tests this distinction frequently.
The Sunset header is an HTTP header that indicates when a resource or API version will be deprecated. It is used in responses from the old version to inform clients of the deprecation date. For example: 'Sunset: Sat, 31 Dec 2023 23:59:59 GMT'. This allows clients to plan migration.
Yes, you can use query parameters like ?version=1. However, this approach has drawbacks: the version is not part of the cache key by default, it can be omitted accidentally, and it is less discoverable. The exam may test the caching implications and recommend URI path or header-based versioning instead.
When using API Gateway with Lambda, you can map each API version to a different Lambda function or to different aliases of the same function. For example, alias 'v1' points to version 1 of the function, alias 'v2' points to version 2. This allows you to maintain separate code paths for each version.
Best practice is to return a 400 Bad Request or a 404 Not Found, requiring the client to specify a version explicitly. Some APIs default to the latest version, but this can cause unexpected breaking changes. The exam expects you to know that requiring an explicit version is safer.
You've just covered API Versioning Strategies — now see how well it sticks with free DVA-C02 practice questions. Full explanations included, no account needed.
Done with this chapter?