API Versioning Policy

API Versioning Policy

You are an API lifecycle strategist. A written versioning and deprecation policy covers:

• Which scheme carries the version.
• What counts as a breaking change.
• How long consumers get before a version dies.
• How you communicate and enforce that death.
• Who signs off on breaking anything.

The hard half is not choosing a scheme - "choosing a versioning strategy is the easy half. The hard half is removing a version without breaking the consumers still on it."

This skill owns the policy: it decides what the scheme and its lifecycle rules are. Sibling samber/developer-platform-skills@public-api-design-review only checks at review time that a scheme exists and is applied consistently.

The wire-level contract is a different versioning surface from the client SDKs wrapping it. SDKs version under plain SemVer, and Stripe is the citable illustration of the split - a date-versioned, account-pinned API next to SemVer SDKs whose major-bump trigger is stricter than the API's version rule. Write the SDK policy separately; this skill covers the contract.

Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

Interview

This is a strategy decision - interview before proposing anything. Ask one question per message, multiple-choice where offered, in this order. Question 1 comes first because its answer changes which later sections even apply.

1. Paradigm: REST/HTTP, GraphQL, gRPC, or several surfaces? (REST defaults to version-and-sunset; GraphQL defaults to continuous schema evolution - see step 1.)
2. Audience: internal only, partner/B2B under contract, fully public, or a mix? (This drives the notice period more than anything else - see step 4.)
3. Current state: greenfield, one unversioned live API, or multiple versions already live? If versions exist: which scheme, and is any version both deprecated and still the default?
4. Breaking-change pressure: how many breaking changes shipped or were blocked in the past year - none, one or two, roughly quarterly, or monthly-plus?
5. Consumer reachability: can you identify and directly contact every consumer? Do any consumers ship mobile apps or run enterprise change-management cycles?
6. Deadline: by what date must this policy - or the pending breaking change forcing it - land?
7. One-off or standing: is this about retiring one version, or a policy the platform will operate for years?
8. Effort ceiling: how much engineering time for versioning machinery, headcount for migration communication, and political capital for governance can you actually spend?

Questions 6-8 exist because the scheme options diverge sharply on time-to-effect, durability, and effort - the ranking in step 3 cannot be picked without them. A hard deadline promotes the low-machinery rungs; a years-long standing policy promotes the expensive ones.

If your harness has persistent memory, store the finished policy's core decisions (scheme, breaking-change definition, notice windows, enforcement style) so later deprecation runs start from the policy instead of re-deriving it.

Audience split: internal / partner / public

The split that drives every number in this policy is consumer reachability: the harder it is to identify and contact every consumer, the longer and more conservative the policy must be.

• Internal consumers get coordinated deploys and contract tests instead of notice periods.
• Partner consumers get negotiated SLAs.
• Fully public consumers get 12-24 months, because mass communication is all you have.

This is why a hyperscaler and a mid-size platform land on the same ~12-month public floor while their internal APIs move in days.

Workflow

1. Settle the paradigm - versioning vs continuous evolution.
2. Write the breaking-change definition.
3. Choose the version scheme.
4. Set the notice windows and concurrent-version count.
5. Design the sunset communication.
6. Choose the enforcement style at the sunset date.
7. Stand up governance proportionate to blast radius.
8. Brainstorm candidate policies, then draft and validate the policy document.

1. Settle the paradigm

REST and GraphQL answer breaking change with different policies, not flavors of one:

• REST/HTTP: version-and-sunset. Ship a new version consumers explicitly opt into, deprecate the old one, retire it on a schedule. Steps 3-6 apply in full.
• GraphQL: continuous evolution. One continuously live schema; clients receive only the fields they request. Add a field, mark the old one @deprecated(reason: "..."), and remove it once telemetry shows zero real consumers. graphql.org states the position outright: GraphQL "takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema."
• The `@deprecated` caveat. Apollo's caveat is the part teams miss: @deprecated "is a documentation and tooling signal, not a removal mechanism" - removal still needs usage monitoring and a written field-rollover strategy. For a GraphQL API, skip step 3's scheme menu and apply steps 4-7 field-by-field instead of version-by-version.
• Neither is paradigm-locked. Shopify date-versions its GraphQL Admin API (YYYY-MM quarterly, same scheme as its REST surface) - a large production counter-example to "GraphQL means no versioning." Zalando's REST guidelines explicitly discourage versioning in favor of additive-only evolution. The paradigm sets the default policy; it does not dictate it.
• gRPC: the breaking-change definition, notice windows, and governance (steps 2, 4, 7) apply unchanged; the scheme menu and HTTP-header communication mechanics in steps 3 and 5 are REST-specific. The gRPC-native equivalents - major version encoded in the proto package (AIP-185), buf breaking-change gates, proto deprecation options - are sibling samber/developer-platform-skills@public-grpc-api-design's territory; use it for the scheme and enforcement layer and keep this skill for the policy layer.

2. Write the breaking-change definition

A deprecation policy without a written breaking-change definition is unenforceable - every dispute becomes a judgment call. Write both lists into the policy:

• Breaking (requires a new version): any change that makes a previously working client fail.
• Removing or renaming a field or endpoint.
• Changing a field's type.
• Removing an enum value.
• Adding a required request parameter.
• Changing the status code or content type for the same scenario.
• Non-breaking (ships into the current version): Stripe's published list is a citable starting taxonomy.
• Adding new resources.
• Adding new optional request parameters.
• Adding new response properties.
• Changing property order.
• Changing the length or format of opaque strings (including ID prefixes).
• Adding new webhook event types.
• Open enums cut version churn: declare which enum fields may grow new values without a version bump, shifting tolerance onto callers instead of onto your compatibility machinery - Stripe documents this as an explicit backward-compatible carve-out.
• A security escape hatch, scoped narrowly: LinkedIn's shape is the standard - even a strict minimum-window policy reserves the right to patch any version "for any critical security, privacy issues, or bug fixes." Write the exception down; never invoke an unwritten one.

Present the definition as a pragmatic simplification, not settled theory - the debate is real and your policy should survive a reader who has seen it.