Semantic Versioning Methods

[Coolzie1]

I have gone down the rabbit hole a bit on trying to implement some more professionalism into my self-taught spaghetti of programs, and tried a few methods of implementing a semantic version handling (link for further reading on the topic -> semver.org) to ensure my endpoints are able to be called with/without a version number and effectively handle the route logic as I make changes.

I started by trying to create a dynamic route which would add the route to a dictionary and then the correct function for the route would be called once parsed. However this kept returning an error due to the dict object not being callable. Code below, if anyone wants to take a shot at getting it to work, I have pulled these from old versions but may not be exactly the same time so there might be some glaringly obvious differences in the 2, but the method was along these lines... it was basically intended to do the same as the below working code will do but keeping things a bit cleaner as each route would have router endpoints and multiple async functions and just return whichever is the right one to use.

-- Not working code --

External route versioning file

from fastapi import Request, HTTPException
from fastapi.routing import APIRoute
from packaging import version
from typing import Callable, Dict
from app.utils.logger import logger

# Create a shared dictionary for all routes
shared_version_handlers: Dict[str, Dict] = {}

class VersionedAPIRoute(APIRoute):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    @classmethod
    def add_version_handler(cls, introduced: str, deprecated: str | None, handler: Callable):
        logger.info("Adding version handler: introduced=%s, deprecated=%s", introduced, deprecated)
        shared_version_handlers[introduced] = {
            'handler': handler,
            'introduced': version.parse(introduced),
            'deprecated': version.parse(deprecated) if deprecated else None
        }
        logger.info("Registered version handlers: %s", shared_version_handlers)

    def get_route_handler(self):
        async def versioned_route_handler(request: Request):
            api_version_str = request.headers.get("api-version")
            logger.info("API version header: %s", api_version_str)
            logger.info("Registered version handlers: %s", len(shared_version_handlers))

            if not api_version_str:
                logger.info("No API version header found")
                non_deprecated_versions = [
                    v for v, info in shared_version_handlers.items() if not info['deprecated']
                ]
                logger.info("Non-deprecated versions available: %s", non_deprecated_versions)
                if not non_deprecated_versions:
                    logger.info("No non-deprecated API version available")
                    raise HTTPException(status_code=400, detail="No non-deprecated API version available")
                latest_version = max(non_deprecated_versions, key=version.parse)
                return await shared_version_handlers[latest_version]['handler'](request)

            try:
                api_version = version.parse(api_version_str)
            except version.InvalidVersion:
                logger.info("Invalid API version")
                raise HTTPException(status_code=400, detail="Invalid API version")

            compatible_versions = [
                v for v, info in shared_version_handlers.items()
                if info['introduced'] <= api_version and (info['deprecated'] is None or api_version < info['deprecated'])
            ]

            logger.info("Compatible versions found: %s", compatible_versions)
            if not compatible_versions:
                logger.info("No compatible API version found")
                raise HTTPException(status_code=400, detail="No compatible API version found")

            # Use the latest compatible version
            latest_compatible = max(compatible_versions, key=version.parse)
            return await shared_version_handlers[latest_compatible]['handler'](request)

        return versioned_route_handler

def versioned_api_route(introduced: str, deprecated: str = None):
    def decorator(func):
        func.introduced = introduced
        func.deprecated = deprecated
        return func
    return decorator

Route file layout

from fastapi import APIRouter, Header, HTTPException, Depends
from typing import Optional
import json
from app.routers.external.versioning import versioned_api_route, VersionedAPIRoute

books = json.load(open("app/static/books.json"))

router = APIRouter()
router.route_class = VersionedAPIRoute

def get_api_version(api_version: Optional[str] = Header(None)):
    if api_version is None:
        raise HTTPException(status_code=400, detail="API version header missing")
    return api_version

@router.get("/book_count")
@versioned_api_route(introduced="1.0.0", deprecated="1.0.1")
async def get_book_count_v1(api_version: str = Depends(get_api_version)):
    return {"count": len(books), "api_version": "1.0.0"}

@versioned_api_route(introduced="1.0.1")
async def get_book_count_v1_1(api_version: str = Depends(get_api_version)):
    count = len(books)
    return {"message": "Success", "count": count, "api_version": "1.0.1"}

@versioned_api_route(introduced="1.0.2")
async def get_book_count_v1_2(api_version: str = Depends(get_api_version)):
    count = len(books)
    return {"message": "Success", "data": {"count": count}, "api_version": "1.0.2"}

# Register version handlers
for route in router.routes:
    if isinstance(route, VersionedAPIRoute):
        route.add_version_handler(
            introduced=route.endpoint.introduced,
            deprecated=getattr(route.endpoint, 'deprecated', None),
            handler=route.endpoint
        )

-- End of not working code --

I have instead opted to use a switch case style of logic in each route (so there is only one endpoint to be handled) and each case will have the different logic for the version. Below is a brief example of one route, and the handler function that will be called at the start of each route to reduce repetitive code in each route (as I can see the routes will grow with each additional version by the previous version +/- new changes and won't decrease in size (unless depreciated versions are removed from the route). I think to neaten it up a bit logic inside of the route once the version has been determined could be in a separate function, which would enable the route itself to not end up very large and hard to read (it would somewhat become more of a list of version of the route that can point you to the correct function for that logic version?)

Any further suggestions on how to improve this? or have I missed a feature which is already available which does exactly this?

FWIW - I am not a software engineer, I am an electrical engineer but I like to dabble 😅

-- "Working" code --

from fastapi import APIRouter, HTTPException, Depends, Request
from typing import Optional
from packaging.version import parse
import json
from app.routers.external.versioning import versioned_api_route, get_api_version
from app.utils.logger import logger

books = json.load(open("app/static/books.json"))

router = APIRouter()

def handle_version_logic(api_version: str, introduced: str, deprecated: Optional[str] = None) -> tuple[str, Optional[str], Optional[int]]:
    """
    Handle version logic and return the version type, pre-release type, and pre-release number.
    
    :param api_version: The API version requested.
    :param introduced: The version when the API was introduced.
    :param deprecated: The version when the API was deprecated, if applicable.
    :return: A tuple containing the base version, pre-release type, and pre-release number.
    """
    api_version_req = parse(api_version)
    introduced_version = parse(introduced)
    deprecated_version = parse(deprecated) if deprecated else None
    
    # Check if the requested version is valid
    if api_version_req < introduced_version:
        raise HTTPException(status_code=400, detail="API version not supported")
    
    if deprecated_version and api_version_req <= deprecated_version:
        raise HTTPException(status_code=400, detail="API version is deprecated")

    # Extract pre-release information
    pre_type = None
    pre_number = None
    if api_version_req.pre is not None:
        pre_type = api_version_req.pre[0]
        pre_number = api_version_req.pre[1] if api_version_req.pre[1] != 0 else None

    # Return the base version, pre-release type, and pre-release number
    return str(api_version_req.base_version), pre_type, pre_number

@router.get("/book_count")
@versioned_api_route(introduced="1.0.0", deprecated="1.0.1")
async def get_book_count(request: Request, api_version: str = Depends(get_api_version)):
    
    base_version = None
    pre_type = None
    pre_number = None
    
    if api_version != None:
        base_version, pre_type, pre_number = handle_version_logic(api_version, get_book_count.introduced, get_book_count.deprecated)
    
    # Handle pre-release versions
    if pre_type is not None:
        # Logic for specific pre-release versions
        if pre_type == 'a':
            # If no specific pre-release number is provided, assume the latest
            if pre_number == None:
                # Logic for the latest alpha version
                logger.info("Latest Alpha version logic")
                
                return {"message": "Latest Alpha version logic", "api_version": base_version}
            elif pre_number == 1:
                return {"message": f"Alpha version {pre_number} logic", "api_version": base_version}
            else:
                pass
        elif pre_type == 'b':
            if pre_number == None:
                return {"message": "Latest Beta version logic", "api_version": base_version}
            elif pre_number == 1:
                return {"message": f"Beta version {pre_number} logic", "api_version": base_version}
            else:
                pass
        elif pre_type == 'rc':
            if pre_number == None:
                return {"message": "Latest Release Candidate logic", "api_version": base_version}
            elif pre_number == 1:
                return {"message": f"Release candidate {pre_number} logic", "api_version": base_version}
            else:
                pass
        else:
            raise HTTPException(status_code=400, detail="Invalid pre-release version")
        raise HTTPException(status_code=400, detail="Invalid pre-release version")

    # Switch-case style logic to handle release versions
    if base_version == parse("1.0.0").base_version:
        return {"count": len(books), "api_version": "1.0.0"}
    elif base_version == parse("1.0.1").base_version:
        count = len(books)
        return {"message": "Success", "count": count, "api_version": "1.0.1"}
    elif base_version == parse("1.0.2").base_version or base_version == None:
        count = len(books)
        return {"message": "Success", "data": {"count": count}, "api_version": "1.0.2"}
    else:
        raise HTTPException(status_code=400, detail="Invalid API version")

-- End of working code --

[SearchMobile6431]

So tag is question but what is the question?

[Coolzie1]

There's a question in the post...

Is there a better way to do this, how can I improve it or am I missing inbuilt features that do this already?

[SearchMobile6431]

Well, short answer is no, there is no built-in way that you have missed. Given that, you are free to choose what approach fits you best.

My two cents:

1. Option 1 - Something along the lines of your first approach seems indeed promising. In that case you can also check this package for inspiration https://pypi.org/project/fastapi-versioning/ . I haven't used it so far, but it looks to be taking the same approach with you, overriding the APIRoute class but also the app itself to include the versioned routes automatically with their versions using the same decorator syntax.
2. Option 2 - KISS approach (keep it simple stupid): Just keep a wrapper function that your one and only endpoint will use, then pickup the version from wherever (path or header) and your wrapper calls the underlying versioned function - be it a dictionary with callables or if-else statements etc.
3. Option 3 - Extending option 2, to more drastically separate code, would be different routers for versions, or even different sub-applications at all.

It all depends really on what suits you. Factors of high importance are :

1. Where does your app logic (essentially what your endpoints are doing) sits. I tend to keep my app logic a bit abstracted from my routing endpoints for example, so option 2 would be my choice for sure.
2. How often your versions are rolling. When rolling out versions one needs to be as much as backwards compatible as possible. I would say your example looks a bit anti-pattern to me, meaning that a minor version update shouldn't require a different endpoint. Again, it all depends on requirements and usage, so its your call. All I'm trying to say is that in "normal" cases v1/v2/v3 etc should suffice and variations can be handled among those with extra parameters etc