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
Add new query parameters
Add new enum values

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

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 changelog for breaking 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 minor version selection in future releases.