API Version Lifecycle
Our API follows a predictable lifecycle with clear deprecation timelines. We provide at least 12 months notice before sunsetting any version.
Lifecycle Stages
Current
Actively developed, receives new features and fixes
Until next releaseSupported
Receives security fixes and critical bug fixes only
12+ monthsDeprecated
No fixes, sunset header present, migration required
6 monthsSunset
Version no longer available, requests return 410 Gone
PermanentVersion History
| Version | Release Date | Status | Sunset Date | |
|---|---|---|---|---|
2024-12-01 | Dec 1, 2024 | current | — | |
2024-09-01 | Sep 1, 2024 | supported | — | |
2024-06-01 | Jun 1, 2024 | supported | — | |
2024-03-01 | Mar 1, 2024 | deprecated | Mar 1, 2025 | |
2023-12-01 | Dec 1, 2023 | deprecated | Dec 1, 2024 | |
2023-09-01 | Sep 1, 2023 | sunset | Sep 1, 2024 |
Deprecation Headers
When calling deprecated endpoints, you'll receive these headers in the response.
| Header | Example Value | Description |
|---|---|---|
Deprecation | true | Indicates the API version or endpoint is deprecated |
Sunset | Sat, 01 Mar 2025 00:00:00 GMT | RFC 7231 date when the version will be sunset |
Link | <https://justkalm.com/docs/migration>; rel="deprecation" | Link to migration documentation |
X-JK-Deprecated-Reason | pricing-model-v2 | Reason code for deprecation |
Typical Timeline
Day 0: New Version Released
New API version becomes current. Previous version moves to supported status.
Month 6: Deprecation Announced
Older versions marked deprecated. Sunset headers added to responses. Migration guide published.
Month 9: Reminder Emails
Email notifications sent to users still on deprecated versions. Dashboard warnings shown.
Month 12: Sunset
Version returns 410 Gone. All requests must use supported versions.
Migration Best Practices
Test in Sandbox First
Use sandbox environment to test new versions before updating production. Both environments support all active versions.
Monitor Deprecation Headers
Log and alert on Deprecation headers in production. Set up monitoring to catch them early.
Subscribe to Changelog
Get notified of new versions and deprecations via RSS, email, or Slack webhook.
Use SDK Updates
Official SDKs handle version headers automatically. Keep SDKs updated for seamless migrations.