Versioning¶

The Backend API uses URL-based versioning to ensure stability while allowing evolution.

Version Format¶

The API version is included in the URL path:

https://api.sartiq.com/api/v1/...
                         ^^
                         version

Current Version¶

Version	Status	Base URL
v1	Current	`https://api.sartiq.com/api/v1`

Versioning Policy¶

Backwards Compatibility¶

Within a major version (e.g., v1), the API maintains backwards compatibility:

We will NOT:

Remove existing endpoints
Remove or rename existing fields in responses
Change the type of existing fields
Change the meaning of existing status codes

We MAY:

Add new endpoints
Add new optional fields to request bodies
Add new fields to response bodies when consumers tolerate unknown fields
Add new query parameters
Add new enum values when consumers handle unknown values

These additions are compatible only for the actual consumer set. Strict response decoders, generated clients with closed schemas, and exhaustive enum handling can make an additive field or enum value incompatible.

Breaking Changes¶

Breaking changes require a new major version (e.g., v2). When a new version is released:

The previous version remains available for a deprecation period
Migration guides are published
Deprecation warnings are added to the old version

The URL API version and the backend repository's semantic version are distinct. The URL selects a client contract; the repository tag identifies a shipped backend revision. Any implemented change that incompatibly alters a public API contract must use ! in its commit/PR header regardless of type. The cross-repository commit and version contract is authoritative for classification and semantic-version derivation.

Deprecation Process¶

gantt
    title API Version Lifecycle
    dateFormat YYYY-MM
    section v1
    Active      :active, v1a, 2024-01, 2025-06
    Deprecated  :v1d, after v1a, 6M
    Sunset      :milestone, v1s, after v1d, 0d
    section v2
    Beta        :v2b, 2025-01, 3M
    Active      :active, v2a, after v2b, 2026-01

Deprecation Timeline¶

Phase	Duration	Description
Active	Ongoing	Full support, recommended for use
Deprecated	6 months	Still functional, migration recommended
Sunset	-	Version removed, requests fail

Deprecation Headers¶

Deprecated endpoints include warning headers:

Deprecation: true
Sunset: Sat, 01 Jan 2025 00:00:00 GMT
Link: <https://docs.sartiq.com/api/migration>; rel="deprecation"

Version Discovery¶

OpenAPI Specification¶

Each version has its own OpenAPI spec:

https://api.sartiq.com/api/v1/openapi.json

API Info Endpoint¶

curl https://api.sartiq.com/api/v1/

{
  "version": "1.0.0",
  "status": "active",
  "documentation": "https://docs.sartiq.com/apis/backend"
}

Migration Guide¶

When migrating between versions, follow these steps:

Review the release notes and migration guide for incompatible changes
Update your base URL to the new version
Test in staging before production
Update error handling for any new error codes
Remove deprecated field usage if applicable

Best Practices¶

For API Consumers¶

Always use the full versioned URL
Don't parse response bodies strictly - ignore unknown fields
Subscribe to API announcements for deprecation notices
Test against new versions in staging before they go live

Version Header (Future)¶

While currently not required, you may include a version header for future compatibility:

X-API-Version: 2024-01-15

This date-based header may be used for API contract negotiation in future releases. It is not the repository's vMAJOR.MINOR.PATCH semantic version and does not affect semantic release derivation.