Fastapi: [QUESTION] recommended way to do API versioning

[x110dc]

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?

[jaddison]

Stripe is a company that I think has figured out a great middleground regarding API versioning - a great writeup on it is https://stripe.com/en-ca/blog/api-versioning.

I wonder how feasible/easy this is to accomplish with FastAPI? I'm not currently a FastAPI user, but am eying it for a future project, and API versioning is a big question I have with it. Would love to hear other answers/if the Stripe approach is feasible with FastAPI.

[euri10]

Hello, I think this is the same question as in
https://github.com/tiangolo/fastapi/issues/200

Le mar. 20 août 2019 à 11:51 PM, James Addison [e-mail] a
écrit :

Stripe is a company that I think has figured out a great middleground
regarding API versioning - a great writeup on it is
https://stripe.com/en-ca/blog/api-versioning.

I wonder how feasible/easy this is to accomplish with FastAPI? I'm not
currently a FastAPI user, but am eying it for a future project, and API
versioning is a big question I have with it. Would love to hear other
answers/if the Stripe approach is feasible with FastAPI.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/tiangolo/fastapi/issues/381?email_source=notifications&email_token=AAINSPUPX2J4W7FLLCXZWKDQFRRNLA5CNFSM4IBI3LEKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4XYU5Y#issuecomment-523209335,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAINSPTN5OBK32UU4YKJDETQFRRNLANCNFSM4IBI3LEA
.

[dmontagu]

I posted a description of an approach to this in #200 (though this issue would probably have been a better place.. I can move it if desired) that I think would enable something akin to the Stripe approach.

[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!

[prostomarkeloff]

I've implemented something along the lines of what @dmontagu suggested in this comment: #200 (comment)
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!

Looks good but I think needed version for routers :) Like:

from fastapi_versioning import VersionedAPIRouter

router = VersionAPIRouter(router, version=(1, 0))

[tiangolo]

If you want completely different API docs (Swagger UI) you could create multiple FastAPI apps, make them all import and include the same routers in several places and import others specific to one app (or version).

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.

If you want to include only some of the endpoints, you could create an APIRouter that includes another router (that creates a copy of all the routes). And then remove the routes that you don't want it to have.

[github-actions[bot]]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.

[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.