verselect

verselect

FastAPI based framework to select an API version.

Battle-tested at Monite in production.

Explanation

At Monite, we are using header-based versioning, meaning that the client has to specify the version of the API it wants to use in the header in the YYYY-MM-DD format.

The issue with this approach is that when releasing a new API version, we need to support it in every service, which is a lot of work. verselect resolves this issue.

How it works

verselect supports waterflowing the requests to the latest version of the API if the request header doesn't match any of the versions.

If the app has two versions: 2022-01-02 and 2022-01-05, and the request header is 2022-01-03, then the request will be routed to 2022-01-02 version as it the closest version, but lower than the request header.

Exact match is always preferred over partial match and a request will never be matched to the higher versioned route

Also non-versioned routes and routers can be added for the endpoints, like webhooks

Usage

from contextvars import ContextVar
from datetime import date

from fastapi import APIRouter
import uvicorn
from starlette.responses import Response

from verselect import HeaderRoutingFastAPI

api_version_var: ContextVar[date] = ContextVar("api_version")
router = APIRouter()
webhook_router = APIRouter()


@router.get("/users")
def users():
    return Response(f"Hello from {api_version_var.get()}", media_type="text/plain")

@webhook_router.get("/webhooks")
def webhooks():
    return Response("webhooks", media_type="text/plain")

versions = [
    "2022-01-10",
    "2022-02-11",
    "1998-11-15",
    "2022-03-12",
    "2027-11-15",
    "2022-04-14",
]
mixed_hosts_app = HeaderRoutingFastAPI(
    api_version_header_name="X-API-Version",
    api_version_var=api_version_var,
)
for version in versions:
    mixed_hosts_app.add_header_versioned_routers(
        router,
        header_value=version,
    )
    mixed_hosts_app.add_unversioned_routers(webhook_router)

if __name__ == '__main__':
    uvicorn.run(mixed_hosts_app)

By running the app, at http://localhost:8000/docs you will see a dashboard with the available versions.

More examples can be found in the tests._resources folder.