# API Versioning & Deprecation Policy

> Official API Lifecycle Specification for Zain Ahmed Engineering Platform
> Canonical URL: https://zainahmed.net/docs/versioning
> Status: Active (v1 Supported)

## 1. Versioning Strategy
- **URI Path Versioning**: All breaking changes are isolated under major version paths (e.g., `https://zainahmed.net/api/v1`).
- **Additive Changes**: Non-breaking additions (optional query parameters, new response fields, additional endpoints) are deployed continuously to the active version.

## 2. 12-Month Deprecation Guarantee
- **Guaranteed Lifecycle**: Any deprecated API version or endpoint is guaranteed a minimum of **12 full months (365 days)** of continued availability before sunset.
- **Migration Documentation**: Dedicated migration guides and automated codemods are published at least 6 months prior to decommissioning.

## 3. RFC 8594 Sunset & Deprecation Headers
When an endpoint is marked for deprecation, all HTTP responses will include:
- `Deprecation: @<unix-timestamp>`
- `Sunset: <http-date>`
- `Link: <https://zainahmed.net/docs/versioning>; rel="deprecation-policy"`