Advanced Versioning

Manage API lifecycles with strict enforcement, deprecation notices, and sunset headers. This works as a more nuanced version of the @deprecated decorator.

Deprecation & Sunset

Gracefully phase out old endpoints by adding Deprecation and Sunset headers to the response.

routes/legacy.py
# Deprecated Version
# Headers: Deprecation: true, Sunset: 2025-12-31
@version("<=1.0.0", deprecated=True, sunset="2025-12-31", message="Please upgrade to v2")
async def legacy_endpoint(): ...

Strict Versioning Enforcement

By default, version checks are permissive. You can force clients to send the X-API-Version header.

If strict_versioning=True is set in app.tinker(), the endpoint will return a 400 Bad Request error if the header is missing.

# main.py
app.tinker(strict_versioning=True)

Detailed Signature

jec/internal/version.py
def version(
    constraint: str, *, 
    deprecated: bool = False, 
    sunset: str = None, 
    message: str = None
)
  • constraint: Comparison string (e.g., ">=1.0.0").
  • deprecated: If True, adds Deprecation: true header.
  • sunset: ISO 8601 date string for endpoint removal (adds Sunset header).
  • message: Custom error message or deprecation notice.