API Versioning and Deprecation Policy: [Organisation or API programme]

Policy that tells API consumers what stays stable, what counts as a breaking change, how and when an API version or feature is deprecated and retired, and how they will be told and helped to migrate. Uses the Deprecation HTTP response header (RFC 9745) and the Sunset HTTP response header (RFC 8594). Replace every [bracketed] value and every row marked Example; the example timelines are reasonable defaults, not requirements.

1. Purpose and scope

This policy lets consumers build on our APIs with confidence and lets our teams evolve them without surprise breakage. It covers [all documented APIs listed in the developer portal]. It does not cover [undocumented endpoints, APIs marked alpha or beta, and internal APIs used by one team only].

2. Versioning scheme

Non-breaking changes are released continuously without a new major version and are listed in the changelog.

3. Compatibility guarantees

Within one major version we guarantee that we will not:

• remove or rename an operation, field, parameter or enum value;
• change the type, format or meaning of an existing field;
• make an optional request field required or add a required parameter;
• change authentication methods or reduce granted scopes;
• change success status codes or documented error types.

Consumers must tolerate, without breaking:

• new response fields and new optional request fields;
• new operations, endpoints and event types;
• new enum values in responses (treat unknown values as a documented default);
• changes to the order of JSON properties and of unsorted lists;
• new HTTP headers and new error type URIs within documented status codes.

4. What is a breaking change

5. Deprecation process and timelines

The diagram shows the lifecycle states of an API version.

6. Deprecation and Sunset headers

• Deprecation (RFC 9745) carries the date the resource was or will be deprecated, as a structured-field date (a Unix timestamp prefixed with @). It does not change how the resource behaves.
• Sunset (RFC 8594) carries the HTTP date after which the resource is expected to stop responding.
• Link headers point to documentation: relation deprecation (RFC 9745) for the deprecation notice and relation sunset (RFC 8594) for the sunset policy.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1767225599
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://developer.example.com/migrations/orders-v1-to-v2>; rel="deprecation"; type="text/html"
Link: <https://developer.example.com/policies/api-deprecation>; rel="sunset"; type="text/html"

For GraphQL use @deprecated(reason: "...") with the removal date in the reason; for gRPC use option deprecated = true plus the changelog; for events add a deprecated note in the schema registry and the AsyncAPI document.

7. Communication

8. Migration support

For every deprecation we provide:

• a migration guide with side-by-side request and response examples;
• a mapping table from old fields or operations to new ones;
• SDK releases supporting the new version before the announcement;
• a usage report per consumer (calls to deprecated features in the last 30 days);
• office hours or a support channel [#api-migrations] during the deprecation period.

9. Exceptions

The timeline can be shortened only for: (a) a security vulnerability that cannot be fixed compatibly; (b) a legal or regulatory requirement; (c) a dependency outside our control (for example a provider shutting down). Shortened timelines need approval from [@cto] and direct contact with every affected consumer. Extensions may be granted to named consumers by [@api-owner] for at most [3 months].

Standard and licence note

Based on common industry practice for API lifecycle policies. The header mechanics follow RFC 9745 (The Deprecation HTTP Response Header Field, March 2025) and RFC 8594 (The Sunset HTTP Header Field); version numbering for SDKs follows Semantic Versioning 2.0.0. No text from those documents is reproduced; consult them for normative requirements. Template licence: MIT.