API versioning strategies in FastAPI - Step-by-Step Execution

Concept Flow - API versioning strategies

Client sends request

↓

Check version info

↓

URL

↓

Route to correct API version

↓

Process request

↓

Send response

The API receives a request, checks the version info from URL, header, or query, then routes to the matching version handler before processing.

Execution Sample

FastAPI

from fastapi import FastAPI, Header
app = FastAPI()

@app.get('/v1/items')
def get_items_v1():
    return {'version': 'v1', 'items': [1, 2, 3]}

@app.get('/v2/items')
def get_items_v2():
    return {'version': 'v2', 'items': ['a', 'b', 'c']}

Defines two API versions using URL path versioning, returning different item lists.

Execution Table

Step	Request URL	Version Detected	Route Chosen	Response
1	/v1/items	v1 (from URL)	get_items_v1	{"version": "v1", "items": [1, 2, 3]}
2	/v2/items	v2 (from URL)	get_items_v2	{"version": "v2", "items": ["a", "b", "c"]}
3	/items	None	404 Not Found	Error: Not Found
4	/items?version=1	v1 (from query)	Depends on implementation	Depends on implementation
5	/items	v2 (from header 'X-API-Version')	Depends on implementation	Depends on implementation

💡 Requests without version info or unknown versions result in 404 or default version handling.

Variable Tracker

Variable	Start	After Request 1	After Request 2	After Request 3
version_detected	None	v1	v2	None
route_chosen	None	get_items_v1	get_items_v2	404 Not Found
response	None	{"version": "v1", "items": [1, 2, 3]}	{"version": "v2", "items": ["a", "b", "c"]}	Error: Not Found

Key Moments - 3 Insights

How does the API know which version to use when the version is in the URL?

The API checks the URL path prefix like '/v1/' or '/v2/' to route to the correct version handler, as shown in execution_table rows 1 and 2.

What happens if the client does not specify any version?

If no version is found in URL, header, or query, the API usually returns 404 or a default version, as shown in execution_table row 3.

Can versioning be done using headers or query parameters instead of URL?

Yes, version info can come from headers or query parameters, but the routing logic must handle these cases explicitly, as hinted in rows 4 and 5.

Visual Quiz - 3 Questions

Look at the execution table, what is the response when the request URL is '/v2/items'?

A {"version": "v2", "items": ["a", "b", "c"]}

B {"version": "v1", "items": [1, 2, 3]}

C Error: Not Found

D Depends on implementation

💡 Hint

Check execution_table row 2 for the response to '/v2/items'

At which step does the API return a 404 Not Found error?

A Step 1

B Step 3

C Step 2

D Step 5

💡 Hint

Look at execution_table row 3 where no version is detected

If the version is sent in the header 'X-API-Version', how does the API detect it?

A From the URL path

B From the query parameter

C From the request header

D It cannot detect headers

💡 Hint

Refer to execution_table row 5 mentioning header version detection

Concept Snapshot

API versioning lets you manage changes without breaking old clients.
Common methods:
- URL path versioning (/v1/items)
- Header versioning (X-API-Version)
- Query parameter versioning (?version=1)
API checks version info, routes request to matching handler, returns response.
No version or unknown version usually means 404 or default handling.

Full Transcript

API versioning strategies help manage different versions of an API so clients can use the version they expect. The API checks the version info sent by the client, which can be in the URL path, a request header, or a query parameter. Based on this, it routes the request to the correct version handler. For example, URL path versioning uses prefixes like '/v1/' or '/v2/' to separate versions. If no version is specified or the version is unknown, the API may return a 404 error or use a default version. This approach keeps old clients working while allowing new features in newer versions.

Practice

1. What is the main purpose of API versioning in FastAPI?

easy

A. To automatically generate API documentation

B. To speed up the API response time

C. To allow multiple versions of an API to coexist and support different clients

D. To encrypt API data for security

Solution

1. Step 1: Understand API versioning concept

   API versioning lets you keep old and new API versions available so different clients can use the version they need.

2. Step 2: Identify the main goal

   The main goal is to support multiple API versions simultaneously without breaking existing clients.

3. Final Answer:

   To allow multiple versions of an API to coexist and support different clients -> Option C

4. Quick Check:

   API versioning = support multiple versions [OK]

Hint: API versioning means supporting old and new API versions [OK]

Common Mistakes:

• Thinking versioning speeds up API
• Confusing versioning with security encryption
• Assuming versioning auto-generates docs

2. Which of the following is a correct way to define a versioned route in FastAPI using the URL path method?

easy

A. app.get('/items/v1')

B. app.get('/v1/items/')

C. app.get('v1items/')

D. app.get('items/v1')

Solution

1. Step 1: Check route path syntax

   FastAPI routes must start with a slash '/' to be valid paths.

2. Step 2: Identify correct version prefix

   Versioning by URL path usually prefixes the version like '/v1/' before the resource path.

3. Final Answer:

   app.get('/v1/items/') -> Option B

4. Quick Check:

   Versioned route starts with '/' and version prefix [OK]

Hint: Routes must start with '/' and include version prefix [OK]

Common Mistakes:

• Omitting leading slash in route path
• Placing version after resource path incorrectly
• Using quotes without leading slash

3. Given this FastAPI code snippet, what will be the response when accessing /api/items with header X-API-Version: 2?

from fastapi import FastAPI, Header, HTTPException
app = FastAPI()

@app.get('/api/items')
async def get_items(x_api_version: str | None = Header(None)):
    if x_api_version == '1':
        return {'version': 1, 'items': ['apple', 'banana']}
    elif x_api_version == '2':
        return {'version': 2, 'items': ['orange', 'grape']}
    else:
        raise HTTPException(status_code=400, detail='Unsupported API version')

medium

A. {'version': 1, 'items': ['apple', 'banana']}

B. HTTP 400 Unsupported API version

C. HTTP 404 Not Found

D. {'version': 2, 'items': ['orange', 'grape']}

Solution

1. Step 1: Check header value handling

   The function reads the header 'X-API-Version' and compares it to '1' or '2'.

2. Step 2: Match header '2' to response

   Since header is '2', it returns the dictionary with version 2 and items ['orange', 'grape'].

3. Final Answer:

   {'version': 2, 'items': ['orange', 'grape']} -> Option D

4. Quick Check:

   Header 'X-API-Version: 2' returns version 2 data [OK]

Hint: Match header value to if-elif branches for output [OK]

Common Mistakes:

• Ignoring header and returning default
• Confusing version 1 and 2 outputs
• Assuming 404 error instead of 400

4. Identify the error in this FastAPI versioning code using query parameters:

from fastapi import FastAPI
app = FastAPI()

@app.get('/items')
async def read_items(version: int = 1):
    if version == 1:
        return {'items': ['pen', 'notebook']}
    elif version == 2:
        return {'items': ['pencil', 'eraser']}
    else:
        return {'error': 'Unsupported version'}

medium

A. The function should raise HTTPException for unsupported versions instead of returning dict

B. The query parameter 'version' should be declared with Query() for validation

C. The route path should include the version like '/v1/items'

D. The default version value should be a string, not int

Solution

1. Step 1: Check error handling for unsupported versions

   Returning a dict with 'error' key is not standard; better to raise HTTPException with status code.

2. Step 2: Understand FastAPI error response best practice

   Raising HTTPException sends proper HTTP error status and message to client.

3. Final Answer:

   The function should raise HTTPException for unsupported versions instead of returning dict -> Option A

4. Quick Check:

   Use HTTPException for errors, not plain dict [OK]

Hint: Use HTTPException for errors, not just return dict [OK]

Common Mistakes:

• Returning error dict instead of raising exception
• Thinking query parameter must use Query() always
• Assuming version must be in URL path

5. You want to support two API versions in FastAPI: version 1 uses URL path versioning like /v1/users, and version 2 uses header versioning with X-API-Version: 2 on the same /users path. How can you implement this correctly?

hard

A. Create two separate routes: one with path '/v1/users' for version 1, and one with path '/users' that checks header 'X-API-Version' for version 2

B. Use a single route '/users' and check both path and header to decide version

C. Use only header versioning for both versions on '/users' path

D. Use query parameter 'version' for both versions on '/users' path

Solution

1. Step 1: Separate version 1 and version 2 routes

   Version 1 uses URL path '/v1/users', so define a route with that path.

2. Step 2: Define version 2 route with header check

   Version 2 uses header on '/users', so define a route '/users' that reads 'X-API-Version' header to confirm version 2.

3. Final Answer:

   Create two separate routes: one with path '/v1/users' for version 1, and one with path '/users' that checks header 'X-API-Version' for version 2 -> Option A

4. Quick Check:

   Separate routes for different versioning methods [OK]

Hint: Separate routes for path and header versioning [OK]

Common Mistakes:

• Mixing path and header versioning in one route
• Using only header or only path for both versions
• Trying to detect path version inside header route