Skip to content

API_VERSIONING_POLICY.md

Latest commit

 

History

History
59 lines (41 loc) · 2.13 KB

API_VERSIONING_POLICY.md

File metadata and controls

59 lines (41 loc) · 2.13 KB
Raw

API Versioning Policy

Versioning strategy

  • New API routes are published under /api/v1/
  • Future versions should be added under /api/v2/, /api/v3/, etc.
  • Path-based versioning is the primary version selection mechanism
  • API clients should prefer explicit /api/v1/... paths when available

Supported version numbers

The middleware validates version strings against the pattern /^v\d+$/ (the letter v followed by one or more digits). Any other format is rejected with 400 Bad Request.

Version Status Notes
v1 Active Current stable version
v2 Planned Reserved for future use

Examples of invalid version strings that are rejected: vABC, v1.2, ../v1, 123.

Compatibility layer

The middleware rewrites legacy API requests from /api/* to /api/v1/*. This ensures:

  • existing clients continue working without immediate changes
  • clients receive a deprecation warning via response headers
  • the application can evolve without breaking older callers

Deprecation warnings

Legacy requests receive the following headers:

  • X-Api-Version: v1
  • X-Api-Deprecated: true
  • X-Api-Deprecation-Info: ...

Clients should log or monitor these headers and migrate to the versioned endpoint.

Migration path

  1. Update clients to call /api/v1/... explicitly.
  2. Add /api/v2/... endpoints for new behavior.
  3. Keep /api/* compatibility until all clients are migrated.
  4. Remove legacy /api/* support only after a deprecation period and communication.

Request handling

  • src/lib/api.ts automatically prefixes internal API client URLs to /api/v1/*
  • legacy URLs still work through middleware rewrite
  • adding a new version requires src/app/api/v2/* route files and optional middleware support