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.