Dr. Amit Puri (amitpuri) - API Versioning & Deprecation Policy

Official versioning lifecycle, deprecation signaling standards, and timeline guarantees for Dr. Amit Puri’s REST API and agentic interfaces.

1. Versioning Strategy

• Active Stable Version: v1
• Path Versioning: Endpoints are served under https://www.amitpuri.com/api/v1/* and aliased at https://www.amitpuri.com/api/*.
• Header Versioning: All API responses return API-Version: v1 and X-API-Version: 1.0.0. Clients may specify API-Version: v1 in request headers.

2. Deprecation Signaling

When an endpoint or API version is marked for deprecation, responses will include standard RFC headers:

• Sunset Header (RFC 8594): Indicates the date of endpoint retirement (e.g. Sunset: Wed, 11 Nov 2026 00:00:00 GMT).
• Deprecation Header (RFC 9745): Indicates the date when deprecation became effective (e.g. Deprecation: @1762819200).
• Link Header (RFC 8288): Links to documentation for successor endpoints (rel="deprecation").

3. Timeline Guarantees

• Minimum Notice Window: A minimum of 90 days notice is provided before any deprecated API is removed.
• Breaking Changes: Breaking changes will always result in a new major version path (e.g. /api/v2/*) leaving existing versions functional through their sunset date.

4. Machine-Readable Endpoints

• JSON Policy: https://www.amitpuri.com/api/deprecation.json
• Versioned JSON Policy: https://www.amitpuri.com/api/v1/deprecation.json
• OpenAPI Specification: https://www.amitpuri.com/openapi.json
• Developer Portal: https://www.amitpuri.com/developers