[QUESTION] recommended way to do API versioning

Description

Is there a recommended way to do API versioning. I know I could use APIRouter and keep all the files for a version in separate subdirectories but that doesn’t seem very DRY.

Is there a way to say “version 1.1 looks just like version 1.0 except in these certain cases”? And save APIRouter for major version changes or rewrites?

[DeanWay]

I’ve implemented something along the lines of what @dmontagu suggested in this comment: https://github.com/tiangolo/fastapi/issues/200#issuecomment-525126712 it’s up on pypi here: https://pypi.org/project/fastapi-versioning/

a more realistic example of it can be found here: https://github.com/DeanWay/fastapi-versioning/tree/master/example

The idea is that each version registered at some point in the app becomes a sub-application mounted at /v{major}_{minor}

each version builds upon the previous, and overrides matching paths.

The parent app’s docs endpoint just lists the versions

The reason for using sub-applications is to separate the openapi.json and docs of each version (kind of a surprise for me that there’s nothing in the openapi spec to handle for mulitple api versions in one document)

I’d like to allow for version headers as well, but I think you still need the url version for openapi to make sense, so maybe some sort of redirection middleware? Might be a terrible idea, not sure yet.

Anyway, might be helpful, take a look, let me know what you think!

[gpakosz]

Hello @tiangolo,

If you want to have different versions in the same API, like http://localhost:8000/api/v1/users and http://localhost:8000/api/v2/users, in recent versions of FastAPI you can include a router more than once with a different path prefix.

With this choice, is it possible to have a generated doc that separates v1 endpoints from v2 endpoints. So far, it seems they’re going to be grouped by tags, e.g. "users" and in that group I will have both /v1/users and /v2/users documented.