Skip to content

API Versioning Strategy

This document describes the API versioning strategy for the Lucid platform, including version negotiation, deprecation policies, and migration guidance.

Versioning Approach

Lucid uses URL-based versioning for its REST APIs. All versioned endpoints include the version prefix in the path (e.g., /v1/passports).

Current Versions

Version Status Support Until
v1 Current -
(unversioned) Deprecated Next major release

Version Negotiation

Response Headers

All API responses include version information headers:

Header Description Example
X-API-Version Current API version v1
X-API-Supported-Versions Comma-separated supported versions v1
Deprecation Set to true for deprecated endpoints true
X-Deprecation-Notice Human-readable deprecation message This endpoint is deprecated...
Link RFC 8288 link to successor endpoint </v1/passports>; rel="successor-version"

Request Headers

Clients can request a specific version using the Accept-Version header:

GET /v1/passports HTTP/1.1
Host: verifier.lucid.computing
Accept-Version: v1
Authorization: Bearer <token>

If an unsupported version is requested, the response includes a warning header:

X-API-Version-Warning: Requested version 'v2' not supported. Using v1.

Endpoint Categories

All new development should use v1 endpoints:

/v1/passports          # List passports with pagination
/v1/passports/{id}     # Get specific passport
/v1/agents             # Agent management
/v1/dashboards         # Dashboard management
/v1/organization       # Organization management
/v1/audit-logs         # Audit log export

Unversioned Endpoints (Deprecated)

Legacy endpoints without version prefix are deprecated:

/passports            # Use /v1/passports instead
/passport/{model_id}  # Use /v1/passports/{id} instead
/sessions             # Use /v1/sessions instead
/users                # Use /v1/users instead

These endpoints return deprecation headers and will be removed in a future release.

System Endpoints (Unversioned)

Health and metrics endpoints remain unversioned as they are infrastructure-level:

/health               # Liveness probe
/health/ready         # Readiness probe
/health/circuits      # Circuit breaker status
/metrics              # Prometheus metrics

Deprecation Policy

Timeline

  1. Announcement: Deprecation announced in release notes and documentation
  2. Warning Period: Deprecated endpoints return Deprecation: true header for minimum 6 months
  3. Removal: Endpoints removed in next major version after warning period

Deprecation Headers

Deprecated endpoints include:

HTTP/1.1 200 OK
Deprecation: true
X-Deprecation-Notice: This endpoint is deprecated. Please use /v1/passports instead.
Link: </v1/passports>; rel="successor-version"

Monitoring Deprecation Usage

Deprecated endpoint access is logged for monitoring:

{
  "event": "deprecated_endpoint_accessed",
  "path": "/passports",
  "client_ip": "192.168.1.1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Migration Guide

From Unversioned to V1

Passports

- GET /passports
+ GET /v1/passports

- GET /passport/{model_id}
+ GET /v1/passports/{passport_id}

Changes: - V1 uses passport_id instead of model_id as the identifier - V1 returns paginated responses with items, total, page, page_size - V1 requires JWT authentication

Sessions

- GET /sessions
+ GET /v1/sessions

- GET /sessions/{session_id}/passports
+ GET /v1/sessions/{session_id}/passports

Changes: - V1 returns paginated responses - V1 requires JWT authentication

Backwards Compatibility

Breaking Changes

The following are considered breaking changes and require a new major version:

  • Removing an endpoint
  • Removing a required request field
  • Removing a response field
  • Changing a field's type
  • Changing authentication requirements
  • Changing error response format

Non-Breaking Changes

The following are non-breaking and can be added to existing versions:

  • Adding new endpoints
  • Adding optional request fields
  • Adding response fields
  • Adding new enum values (with caution)
  • Adding new error codes

Client Implementation

  1. Always use versioned endpoints for new integrations
  2. Check deprecation headers and log warnings
  3. Handle version warnings gracefully
  4. Pin to specific version in production code

Example Client Code

import httpx

class LucidClient:
    def __init__(self, base_url: str, api_version: str = "v1"):
        self.base_url = base_url
        self.api_version = api_version

    def _check_deprecation(self, response: httpx.Response):
        if response.headers.get("Deprecation") == "true":
            notice = response.headers.get("X-Deprecation-Notice", "")
            logger.warning(f"Deprecated endpoint used: {notice}")

    async def list_passports(self, page: int = 1, page_size: int = 20):
        url = f"{self.base_url}/{self.api_version}/passports"
        response = await self.client.get(
            url,
            params={"page": page, "page_size": page_size},
            headers={"Accept-Version": self.api_version}
        )
        self._check_deprecation(response)
        return response.json()

Future Versions

V2 Considerations (Planned)

When v2 is introduced, it may include:

  • GraphQL support alongside REST
  • Enhanced filtering and querying
  • Batch operations
  • WebSocket real-time updates

Version Sunset Policy

  • v1: Long-term support, no planned sunset
  • Unversioned: Sunset after v2 release + 6 months