BanGUI/Docs/API_VERSIONING.md

API Versioning Strategy

Status: Active — Current version: v1

All BanGUI API endpoints are versioned using URI path versioning (e.g., /api/v1/). This document explains when and how to version endpoints, how deprecation works, and what guarantees consumers can rely on.

---

1. Version Lifecycle

Stage	Meaning
Current	Active, receiving new features and bug fixes.
Deprecated	Still functional but marked for removal. Clients receive Deprecation: true and Sunset: <date> response headers.
Removed	Endpoint no longer exists. Clients must migrate to a newer version.

---

2. URL Structure

/api/v{major}/<resource>/<path>

• v1 — current version (released 2026-05-02)
• v2 — reserved; skeleton router deployed at /api/v2/jails but not yet active for production traffic
• PATCH versions (v1.1, v1.2) are not used; only major version bumps indicate breaking changes
• The OpenAPI schema is always available at /api/openapi.json regardless of version

---

3. What Triggers a Version Bump

A new major version is required when a breaking change must be introduced, including:

• Removing or renaming a field in a response model
• Changing the type of a request or response field
• Removing an endpoint entirely
• Changing authentication/authorization semantics
• Modifying the semantics of an existing operation

Non-breaking changes (backward-compatible):

• Adding new optional request fields
• Adding new response fields
• Adding new endpoints
• Fixing bugs that caused incorrect behavior

These do not require a version bump.

---

4. Deprecation Policy

When an endpoint is deprecated:

1. The endpoint remains functional for a minimum of 6 months from the Sunset date
2. Response headers are added to every 2xx response:

   Deprecation: true
   Sunset: <RFC-5322 date>
   Link: <https://bangui.example.com/api/v2/...>; rel="successor-version"
   

3. The endpoint is registered in the deprecation middleware (app/middleware/deprecation.py)
4. The OpenAPI schema marks the endpoint with deprecated: true
5. Documentation is updated to show the endpoint as deprecated

Implementing Deprecation Headers

The DeprecationHeaderMiddleware (app/middleware/deprecation.py) automatically injects the correct headers for any registered deprecated endpoint. To schedule an endpoint for removal:

from datetime import datetime, timezone, timedelta
from app.middleware.deprecation import register_deprecated_endpoint

# Example: deprecate /api/v1/jails on 2026-11-03 (6 months from v2 release)
register_deprecated_endpoint(
    path_prefix="/api/v1/jails",
    sunset_date=datetime(2026, 11, 3, tzinfo=timezone.utc),
    successor_url="/api/v2/jails",
)

The middleware runs on every response; if the request path matches a registered deprecated prefix, the appropriate headers are appended before the response is returned.

---

5. Backend Development: Adding Versioned Endpoints

New endpoints

All new endpoints are added to the current version (/api/v1/). Prefix your router:

router = APIRouter(prefix="/api/v1/my-resource", tags=["My Resource"])

Breaking changes requiring v2

1. Create a new router file (e.g., routers/my_resource_v2.py) with the v2 prefix:

   router = APIRouter(prefix="/api/v2/my-resource", tags=["My Resource (v2)"])
   

2. Copy or adapt the v1 handler logic as needed. Extract shared business logic into a service layer function so both routers call the same underlying code.
3. Register the new router in app/main.py:

   app.include_router(my_resource_v2.router)
   

4. Register the v1 endpoint for deprecation headers (see §4 above)
5. Update this document to reflect the new version lifecycle

Keeping routers DRY

Routers should only contain HTTP concerns (parameters, responses, status codes). Business logic belongs in the service layer. Both v1 and v2 handlers can call the same service function.

---

6. Frontend Development

The frontend always uses the current version's base URL:

const BASE_URL: string = import.meta.env.VITE_API_URL ?? "/api/v1";

All endpoint paths in frontend/src/api/endpoints.ts are defined as relative paths (e.g., /bans, /jails) and are appended to BASE_URL at runtime.

When v2 is released, update VITE_API_URL in the environment configuration to point to /api/v2.

---

7. OpenAPI / Documentation

• Swagger UI: /api/docs
• ReDoc: /api/redoc
• OpenAPI schema: /api/openapi.json
• Docs are not versioned; they always reflect the current (latest) API version

---

8. CI Breaking-Change Checks

A GitHub Actions job runs on every pull request to detect breaking OpenAPI changes:

• openapi-breaking-changes job (PR only): generates the current OpenAPI spec and compares it against the baseline committed on the last push to main. If any breaking changes are found, the job fails and the PR cannot be merged.
• openapi-baseline-commit job (main push only): generates and commits the current OpenAPI spec as the new baseline for future PR comparisons.

To trigger the baseline update, push to main after merging a version bump or any change that legitimately alters the OpenAPI surface.

---

9. Version History

Version	Status	Released	Sunset Date	Notes
v1	Current	2026-05-02	—	Initial versioning; all endpoints moved from /api/ to /api/v1/
v2	Reserved — skeleton active, endpoints not yet available	—	—	Router skeleton at app/routers/jails_v2.py; real endpoints will be added before activation