API Versioning, Deprecation & Sunset Policy
CorporateSaathi is committed to backwards compatibility and predictable API lifecycle management. This policy governs how we version, deprecate, and sunset API endpoints.
Versioning Strategy
All CorporateSaathi API endpoints use URL path versioning (e.g., /api/v1/services).
You may also specify the version using the API-Version: 1.0 request header as a secondary mechanism.
The current production version is v1. All versioned endpoints respond with anX-API-Version header.
Deprecation Lifecycle
| Phase | Timeline | What Happens |
|---|---|---|
| 1. Announcement | Day 0 | Deprecation header is added to the endpoint response with the deprecation date. |
| 2. Notice Period | 180 days | Sunset header is added with the exact removal date.Link header points to the successor endpoint. |
| 3. Warning | Last 30 days | Endpoint returns HTTP 299 Deprecation Warning in addition to normal responses. |
| 4. Sunset | After Sunset date | Endpoint returns HTTP 410 Gone with a JSON body pointing to the replacement. |
RFC 8594 Headers
# Example response headers for a deprecated endpoint
Deprecation: Sat, 01 Mar 2025 00:00:00 GMT
Sunset: Sun, 31 Aug 2025 23:59:59 GMT
Link: <https://corporatesaathi.com/api/v2/services>; rel="successor-version"
X-API-Version: 1.0.0
- Deprecation: The date the endpoint was marked deprecated (RFC 8594).
- Sunset: The final date the endpoint will remain available (RFC 8594).
- Link: Points to the successor endpoint or migration docs (RFC 8288).
Migration Support
When an endpoint is deprecated, we provide migration guides, code samples, and a successor endpoint. Enterprise integrators can request extended notice via our developer support.
Current API status: All v1 endpoints are active with no planned deprecations.
Questions About API Versioning?
Contact our developer support team for migration assistance, custom SLAs, or extended deprecation notices.
Contact Developer Support