Skip to content

Main App

Cadwyn's standard usage involves a single customized FastAPI app: cadwyn.Cadwyn. It accepts all the same arguments as FastAPI does and two more keyword-only arguments:

  • Required versions: VersionBundle describes all versions within your application
  • Optional api_version_parameter_name: str = "x_api_version" is the parameter that Cadwyn will use for routing to different API versions of your app

After you have defined the main app, you can add versioned API routers to it using Cadwyn.generate_and_include_versioned_routers(*routers)

from cadwyn import VersionedAPIRouter, Cadwyn
from versions import my_version_bundle


router = VersionedAPIRouter(prefix="/users")


@router.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@router.get("/users/{username}", tags=["users"])
async def read_user(username: str):
    return {"username": username}


app = Cadwyn(versions=my_version_bundle)
app.generate_and_include_versioned_routers(router)

That's it! generate_and_include_versioned_routers will generate all versions of your routers based on the versions argument.

Routing

Cadwyn is built on header-based routing. First, we route requests to the appropriate API version based on the version header (x-api-version by default). Then we route by the appropriate url path and method. Currently, Cadwyn only works with ISO date-based versions (such as 2022-11-16). If the user sends a date that does not have an exact match, Cadwyn picks up the closest lower applicable version. For example, 2022-11-16 in request can be matched by 2022-11-15 and 2000-01-01 but cannot be matched by 2022-11-17.

However, header-based routing is the default way to use Cadwyn. If you want to use any other form of routing, you can use Cadwyn directly through cadwyn.generate_versioned_routers or subclass cadwyn.Cadwyn to use a different router and middleware. Just remember to update the VersionBundle.api_version_var variable each time you route some request to a version. This variable allows Cadwyn to do side effects and data migrations.

VersionedAPIRouter

Cadwyn has its own API Router class: cadwyn.VersionedAPIRouter. You are free to use a regular fastapi.APIRouter but cadwyn.VersionedAPIRouter has a special decorator only_exists_in_older_versions(route) which allows you to define routes that have been previously deleted. First you define the route and than add this decorator to it.