API versioning strategies in FastAPI

Introduction

API versioning helps keep your app working well when you add new features or change things. It lets old and new users use the API without problems.

You want to add new features without breaking old apps using your API.

You need to fix bugs or improve your API but keep old versions running.

You want to support different clients that expect different API behaviors.

You plan to change the API structure but want to avoid sudden breaks.

You want to clearly organize your API updates over time.

Syntax

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/v1/items")
async def get_items_v1():
    return {"version": "v1", "items": ["apple", "banana"]}

@app.get("/v2/items")
async def get_items_v2():
    return {"version": "v2", "items": [{"name": "apple"}, {"name": "banana"}]}

Versioning can be done in the URL path, query parameters, or headers.

URL path versioning is the simplest and most common method.

Examples

Versioning using the URL path with 'v1' prefix.

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/v1/users")
async def users_v1():
    return {"version": "v1", "users": ["Alice", "Bob"]}

Versioning using a custom header 'X-API-Version'.

FastAPI

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/users")
async def users(x_api_version: str | None = Header(default="1")):
    if x_api_version == "1":
        return {"version": "v1", "users": ["Alice", "Bob"]}
    elif x_api_version == "2":
        return {"version": "v2", "users": [{"name": "Alice"}, {"name": "Bob"}]}
    else:
        raise HTTPException(status_code=400, detail="Unsupported API version")

Versioning using a query parameter 'api_version'.

FastAPI

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
async def users(api_version: str = Query("1")):
    if api_version == "1":
        return {"version": "v1", "users": ["Alice", "Bob"]}
    elif api_version == "2":
        return {"version": "v2", "users": [{"name": "Alice"}, {"name": "Bob"}]}
    else:
        return {"error": "Unsupported API version"}

Sample Program

This FastAPI app uses a custom header 'X-API-Version' to decide which version of the items list to return. If the header is '1', it returns a simple list. If '2', it returns a list of objects. If the version is unsupported, it returns an error.

FastAPI

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/items")
async def read_items(x_api_version: str | None = Header(default="1")):
    if x_api_version == "1":
        return {"version": "v1", "items": ["apple", "banana"]}
    elif x_api_version == "2":
        return {"version": "v2", "items": [{"name": "apple"}, {"name": "banana"}]}
    else:
        raise HTTPException(status_code=400, detail="Unsupported API version")

Important Notes

Using URL path versioning is easy to understand and test.

Header or query parameter versioning keeps URLs clean but needs clients to send extra info.

Always document your API versions clearly for users.

Summary

API versioning helps keep old and new API users happy.

Common ways: URL path, headers, or query parameters.

Choose the method that fits your app and users best.