API Versioning and Migration Guide
Prerequisites
Versioning Strategy
Aelix uses URL path versioning. The major version is embedded in the base path:
https://api.aelix.digitalapi.ai/v1/accounts ← Current stable
https://api.aelix.digitalapi.ai/v2/accounts ← Next major version (beta)
Minor changes (new optional fields, new endpoints) are non-breaking and released into the same major version without notice. Breaking changes always increment the major version.
Deprecation Timeline
| Phase | Duration | What Happens |
|---|---|---|
| Stable | — | Full support and SLA |
| Deprecated | 12 months | Warning headers added; new features go to v+1 only |
| Sunset | 3 months | Returns 410 Gone for all requests |
Deprecation is announced via email, the changelog, and the Sunset HTTP response header.
Detecting Deprecation Warnings
Check for the Deprecation and Sunset headers in API responses:
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://aelix.digitalapi.ai/migration/v1-to-v2>; rel="deprecation"
Migration Checklist: v1 → v2
- Read the v2 migration guide and identify breaking changes
- Create a v2 test environment and run your integration tests against it
- Update base URL from /v1/ to /v2/ in your configuration
- Update request/response models to match new field names
- Deploy to production with a feature flag to switch traffic gradually
- Monitor error rates for 48 hours before fully retiring v1 calls