Merge pull request #60 from febus982/resource_base_versioning

Resource based API versioning

Author: febus982

Dockerfile

@@ -1,4 +1,5 @@
-FROM python:3.11-slim as base
+ARG PYTHON_VERSION=3.11
+FROM python:$PYTHON_VERSION-slim as base
 ARG UID=2000
 ARG GID=2000
 RUN addgroup --gid $GID nonroot && \

README.md

@@ -21,16 +21,18 @@ In this way our components are loosely coupled and the application logic
 (the domains package) is completely independent of the chosen framework
 and the persistence layer.
 
-## HTTP API Docs
+## HTTP API Docs and versioning
 
-This application uses [fastapi-versionizer](https://github.com/alexschimpf/fastapi-versionizer)
-to provide easy API schema version management.
+API documentation is provided by [FastAPI](https://fastapi.tiangolo.com/features/)
+on `/docs` and `/redoc` paths using OpenAPI format.
 
-There are 3 different API documentation paths:
+I believe that versioning an API at resource level provides a much more
+flexible approach than versioning the whole API.
 
-* `/api/v1/docs` and `/api/v1/redoc`: v1 OpenAPI schema
-* `/api/v2/docs` and `/api/v2/redoc`: v2 OpenAPI schema
-* `/docs` : non-versioned routes OpenAPI schema (e.g. health check endpoint)
+The example `books` domain provides 2 endpoints to demonstrate this approach
+
+* `/api/books/v1` (POST)
+* `/api/books/v2` (POST)
 
 ## Package layers
 

http_app/__init__.py

@@ -1,14 +1,13 @@
 from typing import Union
 
 from fastapi import FastAPI, Request
-from fastapi_versionizer import versionize
 from starlette.responses import JSONResponse
 from starlette_prometheus import PrometheusMiddleware, metrics
 from structlog import get_logger
 
 from config import AppConfig, init_logger
 from domains import init_domains
-from http_app.routes import init_unversioned_routes, init_versioned_routes
+from http_app.routes import init_routes
 from storage import init_storage
 
 
@@ -23,20 +22,9 @@ def create_app(
 
     init_storage()
 
-    app.add_middleware(PrometheusMiddleware)
+    init_routes(app)
 
-    init_versioned_routes(app)
-    versionize(
-        app=app,
-        prefix_format="/api/v{major}",
-        docs_url="/docs",
-        redoc_url="/redoc",
-    )
-
-    """
-    Routes initalised after `versionize` are not versioned
-    """
-    init_unversioned_routes(app)
+    app.add_middleware(PrometheusMiddleware)
     app.add_route("/metrics/", metrics)
 
     return app

http_app/routes/__init__.py

@@ -1,30 +1,10 @@
 from fastapi import FastAPI
-from fastapi.openapi.docs import get_swagger_ui_html
-from starlette.responses import HTMLResponse
 
-from http_app.routes.api.books import router as api_books_router
-from http_app.routes.graphql import graphql_app
-from http_app.routes.hello import router as hello_router
-from http_app.routes.ping import router as ping_router
+from http_app.routes import api, graphql, hello, ping
 
 
-def init_versioned_routes(app: FastAPI) -> None:
-    app.include_router(api_books_router)
-
-
-def init_unversioned_routes(app: FastAPI) -> None:
-    app.include_router(ping_router)
-    app.include_router(hello_router)
-    app.include_router(graphql_app, prefix="/graphql")
-
-    @app.get("/docs", response_class=HTMLResponse, include_in_schema=False)
-    async def get_api_versions() -> HTMLResponse:
-        """
-        Swagger page for non-versioned routes.
-        """
-
-        return get_swagger_ui_html(  # pragma: no cover
-            openapi_url=f"{app.openapi_url}",
-            title=f"{app.title}",
-            swagger_ui_parameters={"defaultModelsExpandDepth": -1},
-        )
+def init_routes(app: FastAPI) -> None:
+    app.include_router(api.router)
+    app.include_router(ping.router)
+    app.include_router(hello.router)
+    app.include_router(graphql.router, prefix="/graphql")

http_app/routes/api/__init__.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from . import books
+
+router = APIRouter(prefix="/api")
+
+router.include_router(books.router_v1)
+router.include_router(books.router_v2)

http_app/routes/api/books.py

@@ -1,10 +1,10 @@
 from fastapi import APIRouter, status
-from fastapi_versionizer import api_version
 from pydantic import BaseModel
 
 from domains.books import Book, BookData, BookService
 
-router = APIRouter(prefix="/books")
+router_v1 = APIRouter(prefix="/books/v1")
+router_v2 = APIRouter(prefix="/books/v2")
 
 
 class CreateBookResponse(BaseModel):
@@ -44,8 +44,7 @@ class Config:
 """
 
 
-@api_version(1)
-@router.post("/", status_code=status.HTTP_201_CREATED)
+@router_v1.post("/", status_code=status.HTTP_201_CREATED)
 async def create_book(
     data: CreateBookRequest,
 ) -> CreateBookResponse:
@@ -54,9 +53,7 @@ async def create_book(
     return CreateBookResponse(book=created_book)
 
 
-# Example v2 API with added parameter
-@api_version(2)
-@router.post("/", status_code=status.HTTP_201_CREATED)
+@router_v2.post("/", status_code=status.HTTP_201_CREATED)
 async def create_book_v2(
     data: CreateBookRequest,
     some_optional_query_param: bool = False,

http_app/routes/graphql/__init__.py

@@ -5,4 +5,4 @@
 
 schema = Schema(query=Query)
 
-graphql_app: GraphQLRouter = GraphQLRouter(schema)
+router: GraphQLRouter = GraphQLRouter(schema)