API versioning and OpenAPI docs

[pawelad]

Hi!

I'm having trouble with the layout of a versioned API and the auto generated OpenAPI schema.

My first attempt was something similar to this:

api_router = Router(path="/api/v1", route_handlers=[views.info])

@get("/info", operation_id="test")
async def info() -> APIInfo:
    """Return basic API info."""
    return APIInfo(
        version=__version__,
        environment=settings.ENVIRONMENT,
        debug=settings.DEBUG,
    )

Seems easy enough, but I noticed that I don't have full control over the operation ID, which (as explained in the docs) will include ApiV1 prefix in all paths which is not what I want

My second attempt was to use OpenAPI's Servers configuration (as in, servers=[Server(url="/api/v1")]) but that turned out even worse, as the server URL was appended to the route URL, which resulted in querying http://127.0.0.1:8000/api/v1/api/v1/info.

I guess my overarching question is - does Litestar (and its OpenAPI plugin) support path based API versioning? If yes, could someone point me in the right direction?

[scott2b]

I would also like to see some discussion around this. Even if not in terms of whether the framework directly supports such a scheme, still in terms of what best practices might be. I believe it is the case that historically RESTful APIs were intended to use headers for the versioning of requests .. but we all know that path based versioning has become something of a pseudo-standard, and stakeholders often expect it.

My current working solution to this seems ok, I guess. It is a bit less than ideal, and I'd like to know how others are approaching this. What I am doing is setting up version-specific routers and then passing them as route handlers to Litestar. It looks something like this:

# API Version 1: Access to dogs and cats
v1_router = Router(
    path="/v1",
    route_handlers=[dogs, cats]
)

# API version 2: We upgraded dogs, and added a hamsters endpoint
v2_router = Router(
    path="/v2",
    route_handlers=[dogs_v2, cats, hamsters]
)

app = Litestar(
    route_handlers=[v1_router, v2_router],
    ...

The primary caveat that I have identified so far with this approach is that all of the endpoints will be documented together in the openapi docs rather than have distinct v1 and v2 docs. So, the docs end up looking something like:

GET /v1/dogs
GET /v2/dogs

GET /v1/cats
GET /v2/cats (Note: this is the same functionality as v1)

GET /v2/hamsters

Although the endpoints are not necessarily in the order you would expect. I am unsure of how that order is determined.
In terms of documenting the interface for end users, it seems less than ideal. Other than that, I have not identified any specific problems. I am unsure of how well route reversal works in this setup, but I suspect, e.g. for cats in this scenario (which is meant to be the same controller in v1 and v2 for the hypothetical scenario), you would want to break it out into two distinct endpoints (with distinct reversal names) that call a common helper function.

Curious to know what better approaches others might be using.

[scott2b]

Realizing now that I described an approach more or less identical to what @pawelad already tried. My solution does not offer anything in terms of addressing the operation ID issue of the original quesetion.

[Goldziher]

Yhea, this returns the discussion to versioning support in general. We oughta support this in some fashion.

[provinzkraut]

The router based approach sounds reasonable to me. Maybe we could do something like per-router API docs? Then that would basically solve this already.

[obrienmd]

Just found this while trying to come up with something better than my current hack: multiple Litestar instances mounted under a single Starlette base app. Using this approach seemed OK until until I looked at docs: The API docs don't know anything about the top-level mounts, so they're missing parts of their paths in the presented URLs - e.g. Swagger shows http://localhost:port/task rather than http://localhost:port/api/v1/task.

I like the idea of per-router API docs - perhaps along with an easy off-switch for API docs on the "parent" router?

Here's some pseudo-code for the approach described above:

from starlette.applications import Starlette
from litestar import Litestar

from .api.v1.task import TaskController as TaskControllerV1
from .api.v2.task import TaskController as TaskControllerV2

api_v1 = Litestar(route_handlers=[TaskControllerV1])
api_v2 = Litestar(route_handlers=[TaskControllerV2])

app = Starlette(debug=True)
app.mount("/api/v1", api_v1)
app.mount("/api/v2", api_v2)

[dbrnz]

This sounds like what I'm wanting to do -- route specific schema endpoints, /route1/schema, /route2/schema, etc.