# API Versioning Strategy ## 1. Consumer Landscape & Change Impact Assessment This API serves two structurally different consumer populations, and the rest of this policy is calibrated to the harder of the two. **External partners (~200 companies).** *Calibrated to stated consumer landscape.* These consumers vary widely in engineering sophistication, and many are small companies with no dedicated engineering resources. Anthropic — rather, the platform — has no direct control over when or whether they upgrade: there is no lever to force a partner onto a new version except a hard sunset date, and even that only works if the partner is paying attention. Historically, breaking-change communication for this group relied on email alone with "mixed success," meaning a real fraction of partners have already experienced unannounced-feeling breakage. This is the population every timeline in Sections 4–6 is sized against. **Internal mobile app.** *Calibrated to stated consumer landscape.* This consumer is fully controlled — it can adopt a new version within a single app-store release cycle (effectively weeks). It could tolerate an aggressive, fast-moving policy on its own, but running a separate, laxer policy just for this one consumer adds process complexity for negligible benefit given it's a single, cooperative integration. **Change-impact implications:** - Additive changes (new optional fields) arrive **monthly**. For consumers with well-behaved, tolerant deserializers this is genuinely non-breaking traffic that needs no version bump at all. *General API design principle, flagged for confirmation:* some fraction of the 200 partners, especially the less sophisticated ones, may run strict/closed schema validation that rejects unrecognized fields — if so, "non-breaking" additive changes could still break them in practice. This risk is carried into Section 3 and restated as an open question in Section 8. - Breaking changes (renamed fields, changed response shapes) arrive roughly **twice a year**. Given the partner population's slow upgrade capacity ("months," not days), a breaking change cadence of every ~6 months means the deprecation window in Section 4 will, by construction, overlap with the *next* breaking release — this policy is built with that overlap in mind rather than pretending each breaking change is independent. - There is currently **no versioning at all** — every consumer, sophisticated or not, hits the same unversioned endpoints. Introducing versioning is therefore a green-field rollout, not a migration between two existing schemes, but it still requires a careful cutover so that today's unversioned traffic doesn't get silently reinterpreted as "whatever version exists" once versioning exists (addressed in Section 5). ## 2. Versioning Scheme Selection & Rationale **Recommendation: URL path versioning** (`/v1/`, `/v2/`, …), applied uniformly to all consumers, including the internal mobile app. *Calibrated to stated consumer landscape:* with 200 partners of "varying levels of engineering sophistication," the versioning mechanism itself has to be nearly impossible to get wrong. A version segment in the URL path is visible in browser bars, curl commands, Postman collections, server logs, and API gateway routing rules without any custom code — a partner with minimal engineering capacity can point their existing integration at a new path with no client-library changes. Header-based versioning (`Accept-Version: v2`) requires every partner to correctly set and maintain a custom header on every request; for a population that already struggled to act on plain deprecation emails, adding a mechanism that depends on partners implementing something extra correctly is added risk with no offsetting benefit. **Date-based versioning is rejected** for this API. *General API design principle.* Date-based versioning suits APIs with frequent, fine-grained releases and consumers sophisticated enough to pin to and reason about a specific release date (e.g., Stripe's model, aimed at professional engineering teams who read changelogs). Here, breaking changes are infrequent (twice a year) and a large share of consumers are not equipped to track dated releases — date versioning would multiply the number of distinct "version lines" support has to reason about without adding real value, since the actual breaking-change cadence doesn't need that granularity. **On CURRENT_VERSIONING_APPROACH:** since no formal versioning exists today, there is no scheme-migration cost to weigh — this is an initial rollout, not a switch. The existing unversioned endpoints are frozen and aliased as `/v1/` at cutover (see Section 5), so no consumer's current behavior changes on the day versioning is introduced. **On the internal mobile app:** it could technically use a lighter-weight mechanism given its fast upgrade cycle, but standardizing on one scheme for all consumers avoids maintaining two parallel versioning code paths for one team's convenience. *General API design principle.* ## 3. Breaking vs. Non-Breaking Change Classification **Breaking changes** (require a new version number, e.g. `/v1/` → `/v2/`): - Removing an existing field from a response - Renaming an existing field (explicitly named in ANTICIPATED_CHANGE_TYPES) - Changing an existing field's data type (e.g., string → integer, single object → array) - Changing a response's structural shape (e.g., re-nesting a field, flattening a previously-nested object) — explicitly named in ANTICIPATED_CHANGE_TYPES - Changing a request field from optional to required - Changing an endpoint's URL path or HTTP method - Removing an endpoint - Changing the meaning of an existing status/error code for a scenario that previously returned a different code - Changing default behavior of an existing parameter when the parameter is omitted **Non-breaking changes** (ship within the current version, no bump required): - Adding a new optional field to a request or response body - Adding a new endpoint - Adding a new optional query parameter - Relaxing a previously-required request field to optional - Adding a new HTTP method to an existing resource path (e.g., adding `PATCH` where only `GET`/`PUT` existed) **Documented exception — new enum values.** Adding a new value to an existing enum (e.g., a new `status` value) is classified **non-breaking at the API level**, but is called out separately because it is a known source of real breakage for consumers who treat enums as closed sets (e.g., a `switch` statement with no default case). Given the "varying levels of engineering sophistication" among the 200 partners, this classification should be paired with explicit guidance in API documentation instructing consumers to handle unknown enum values gracefully, and any enum expansion should be announced (not silently shipped) even though it doesn't trigger a version bump. *General API design principle, flagged in Section 8 pending confirmation of whether this has already caused incidents.* **Documented exception — unknown fields on additive changes.** Adding a new optional field is classified non-breaking under the API's own contract, but whether it is *actually* non-breaking for every partner depends on whether any partners validate against a closed/strict schema. This can't be resolved from the API side alone; it is carried forward as an open question in Section 8 rather than silently assumed away. ## 4. Deprecation & Sunset Policy Given the partner population's stated upgrade constraint — "months" to upgrade, no dedicated engineering resources for many — the deprecation window is sized well above what an internal-only API would need, per the Section 1 assessment. **Deprecation window: 12 months from the release of the replacing version.** *General API design principle (12 months is a common floor for public APIs with mixed-sophistication consumer bases) combined with the Section 1 finding that many partners lack dedicated engineering staff and upgrade on a "months," not "weeks," timeline.* The exact number should be treated as provisional pending real upgrade-behavior data — see `<NEEDS-INPUT: partner-upgrade-time-distribution>` in Section 8 — but 12 months is the recommended default given what's currently known. Because breaking changes ship roughly twice a year and each deprecated version stays live for 12 months, at steady state **up to three version lines may be live concurrently** (current + two prior). This is a direct, stated consequence of the twice-yearly cadence combined with the 12-month window, not an incidental cost — Section 8 asks whether this level of concurrent-version maintenance is actually tolerable, since if not, either the breaking-change cadence or the window length needs to change, not this policy's honesty about the tradeoff. **Signals sent to consumers during the deprecation window**, layered rather than relying on a single channel — a direct response to the stated fact that email-only communication previously had "mixed success": - `Deprecation` and `Sunset` HTTP response headers (per the IETF draft convention) on every response from a deprecated version, so automated tooling on the partner's side can detect it even if no human reads an email. - Direct email to the registered technical contact for every partner API key, sent at the 12-month, 6-month, 1-month, and 2-week marks before removal. - A status/changelog page documenting every deprecation with the exact removal date, linked from API documentation. - For partners still actively calling a deprecated version inside 60 days of sunset, proactive individual outreach (not just another automated email) given that the historical email-only approach is known to under-perform for this population — *Calibrated to stated consumer landscape.* **Internal mobile app:** covered by the same window and signals for consistency, but in practice its release-train cycle means it will typically migrate well before the 12-month mark; no separate fast-track policy is needed. ## 5. Version Negotiation & Communication Mechanism **Mechanism:** the version is specified as a URL path segment immediately after the host (`/v1/orders`, `/v2/orders`). **Cutover from the current unversioned state:** at the moment versioning is introduced, all existing unversioned endpoints are frozen and aliased as `/v1/` — no partner's behavior changes on cutover day. **No silent default-to-latest.** *This directly follows Design Principle C.* Given breaking changes occur twice a year and the partner base includes many unsophisticated consumers, silently routing any unversioned or ambiguous request to the newest version would mean a partner's integration could break with zero code change on their part — the worst possible failure mode for exactly the consumers least equipped to diagnose it. **Recommended default behavior for unversioned requests, once versioning exists:** - The legacy unversioned route is kept alive for a transition period, but is treated as **pinned to `v1`** (the version that existed at cutover) — not routed to "latest." This gives partners who haven't yet noticed versioning exists a stable, unsurprising floor rather than a moving target. - All *new* integrations, and all documentation going forward, require an explicit version segment — there is no "no version specified, please guess" path for new consumers. - The unversioned route is itself put on the same deprecation timeline as any other version (Section 4), with the explicit goal of eventually requiring every request to name its version. ## 6. Migration Support Strategy Given the partner base's limited engineering sophistication, migration support is weighted toward reducing the amount of independent engineering work a partner has to do, not just documenting the change and leaving them to it. - **Migration guide per breaking release:** a plain-language, field-by-field diff (old shape → new shape, with a short "why") published alongside the new version — not just a terse changelog entry, since a changelog assumes a level of engineering fluency this population doesn't uniformly have. - **Side-by-side live period:** the old and new versions are both fully live for the entire 12-month deprecation window (Section 4), so partners can migrate on their own schedule rather than in a forced cutover. - **Sandbox/staging environment:** partners can point test traffic at the new version with sample data before touching production, reducing the risk that migration itself introduces an outage. - **Reference client tooling:** an updated Postman collection and, where feasible, updated code samples for the new version, published with the migration guide — lowers the bar for partners without dedicated engineering time to hand-write a new integration from a spec. - **Direct outreach cadence:** because breaking changes are infrequent (twice a year, not weekly), it is operationally feasible to pair each breaking release with scheduled office hours or a walkthrough call offered to partners, rather than relying solely on the email channel that previously underperformed. *Calibrated to stated consumer landscape* — this would not scale at a higher change frequency, but it does at this one. - **Internal mobile app:** migration is coordinated directly with the mobile team ahead of the public release, since it's a single, controlled integration rather than 200 independent ones. ## 7. Governance & Change Review Process - Every proposed API change is classified against Section 3's rules by a designated API owner (or a small API review group, if the team is large enough to warrant one) **before** it ships, not after a partner reports something broke. - Any change that isn't a clean match to Section 3's explicit lists — including the documented enum and unknown-field gray areas — is escalated to this reviewer rather than being decided ad hoc by whoever is implementing it. This is the direct mechanism preventing Section 3's rules from being informally overridden under deadline pressure. - **Breaking changes require explicit sign-off** from the API owner before merge, and are batched into the twice-yearly planned release windows established in Section 4 rather than shipped opportunistically — this keeps the total number of things a partner has to track per year small and predictable. - **Automated backstop:** contract/schema-diff tooling in CI flags any change matching Section 3's breaking criteria and blocks it from merging into a stable version's branch without the sign-off above. This exists specifically so a change someone believes is "probably fine" cannot slip into a stable version without a human with authority confirming that classification. ## 8. Open Questions & Data Requests - `<NEEDS-INPUT: partner-upgrade-time-distribution>` — actual data on how long partners have historically taken to act on past changes, and whether "months" skews toward 2–3 or toward 9–12, would let the 12-month deprecation window in Section 4 be tightened or lengthened with confidence rather than set as a general-principle default. - `<NEEDS-INPUT: email-communication-failure-diagnosis>` — what specifically caused email-only communication to have "mixed success" historically (wrong/outdated contacts, low open rates, notifications ignored as noise)? The answer determines whether the layered communication plan in Section 4 (headers + email + outreach) actually addresses the root cause or just adds channels around the same underlying problem. - `<NEEDS-INPUT: strict-schema-partner-count>` — whether any meaningful number of the 200 partners use strict/closed schema validation that would reject new optional fields or unrecognized enum values, which would mean some "non-breaking" changes in Section 3 aren't actually safe for every consumer as classified. - `<NEEDS-INPUT: concurrent-version-maintenance-tolerance>` — whether running up to three live version lines at once (a direct consequence of the twice-yearly breaking cadence combined with the 12-month window in Section 4) is operationally acceptable, or whether either the cadence or the window needs to shrink. - Is there an existing partner/API-key registry capable of tracking per-partner version usage? The proactive, targeted outreach recommended in Section 4 and 6 depends on being able to identify which partners are still on a version approaching sunset. - Do any of the 200 partner contracts already contain minimum-notice clauses for breaking changes that would override or constrain the timelines recommended here?