multiple API versions with common response model

[davidegraff]

Hello!

I'm currently using FastAPI to develop a web app with multiple "versions" that will be deployed simultaneously. I.e., I have both a v1 and v2 API that are related and I would like to have both accessible. Both v1 and v2 support the abstract operation Foo -> list[Bar], but they both differ in the structure of Bar. Currently, I have the repository structured something like this:

app
├── common
│   └── schemas
│       ├── foo.py
├── v1
│   ├── schemas
│       ├── bar.py
├── v2
│   ├── schemas
│       ├── bar.py

So it's possible to have some common FooRequest that both versions accept, but I'm wondering if there is some way to abstract away the FooResponse structure as well. As mentioned above, the abstract API is of the form FooRequest -> FooReponse, where FooReponse : List[Bar], but both version 1 and 2 differ in the concrete structure of Bar. If possible, I'd like to avoid writing the boilerplate FooReponse schema for both v1 and v2 and instead place this schema under app/common/schemas/foo.py. Is this possible with the current app structure or would I need to structure it differently? Thanks for the help!

[extreme4all]

you can create app/common/schemas/bar.py and import it like you import your schema
here is some sample code whhat it would look if you extended the response class, if you are going to completely change the class i would suggest creating a new one

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class FooRequest(BaseModel):
    foo: str

class FooResponsev1(BaseModel):
    foo: str
    bar: str

class FooResponsev2(FooResponsev1):
    baz: str

@app.post('/v1', response_model=FooResponsev1)
async def routerV1(request: FooRequest):
    return FooResponsev1(foo=request.foo, bar=request.foo)
    
@app.post('/v2', response_model=FooResponsev2)
async def routerV2(request: FooRequest):
    return FooResponsev2(foo=request.foo, bar=request.foo, baz=request.foo)

if __name__ == "__main__":
    uvicorn.run("response_model:app", host="localhost", port=5000, workers=1, reload=True)

[davidegraff]

Thanks for the response! Your suggestion was my first thought, but I was hoping for a slightly more "abstract" response model. Taking your example above:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class FooRequest(BaseModel):
    foo: str

class Bar(BaseModel):
    pass

class FooResponse(List[Bar]):
    pass

@app.post('/v1', response_model=FooResponse)
async def routerV1(request: FooRequest):
    return FooResponsev1(foo=request.foo, bar=request.foo)
    
@app.post('/v2', response_model=FooResponse)
async def routerV2(request: FooRequest):
    return FooResponsev2(foo=request.foo, bar=request.foo, baz=request.foo)

and then in the v1 and v2 modules:

# app/v1/schemas/bar.py
class BarV1(Bar):
    xs: list[str]

# app/v2/schemas/bar.py
class BarV2(Bar):
    xs2ys dict[str, float]

The broad strokes differences between the v1 and v2 APIs are that while v1 returns just a list of xs, the v2 API returns not only the xs but also their "amounts" (ys). So it seems I have a few possibilities:

1. define a separate response model in each version's schema. This isn't bad, but there's some boilerplate in that the general FooResponse is always a list[Bar], but the specifics of what a Bar is are version-dependent
2. "upgrade" BarV1 to be synonymous with BarV2. This way the definition of a Bar can be moved to app/common/schemas/bar.py. However, this seems a little like fitting a square peg in a round hole because the BarV1 schema just becomes dict[str, None]. Again, we can iterate through this just like a list and get the same functionality, but it "bloats" the schema in a sense. the v1 schema is sort of "bare-bones" while the v2 schema is more "enriched", and I'd like their implementations to reflect that.

So I'm not sure if what I want can be done, and ultimately it's not the biggest thing in the world to just stick to option (1), but I figured I'd ask here to see if anyone had any ideas!

[DannyVarod]

The whole point of having a v2 is usually to enable a different API without breaking existing clients.
Since for v1 you need to keep the existing schema and for v2 you want a different schema, using a shared schema is risky, because you might end up breaking v1 while changing for the new v2.

What you might want to consider is refactoring v1 implementation to an adaptor above v2 - translate the v1 schema to v2 schema and call the underlying v2 logic, then translating the v2 response back to v1. You could also use this technique to map from v2 to a non-FastAPI based model for your storage/business-logic and back, thus isolating your storage/business-logic model from your API model.

[davidegraff]

that's more or less what I ended up doing, but didn't have any firm reasoning behind it. Thanks for the explanation!