How to retire a partner API version without stranding clients

Find the clients behind the traffic

An API version should be retired because maintaining it imposes a real cost or prevents a needed change, not because a new route looks cleaner. Begin with an inventory of endpoints, methods, request fields, response fields, error behaviour and authentication for the old and replacement versions. Then link requests to actual client organisations using the identifiers already available in your access records. A count of calls alone cannot tell you whether a quiet monthly reconciliation job still depends on the old endpoint. Record the owner and technical contact for each integration, the business process it supports, and its normal cadence. Review privacy and retention controls before exporting logs into a planning sheet; the team needs client and endpoint patterns, not tokens or full customer payloads.

Separate clients that can upgrade themselves from those whose software is managed by a vendor, a franchisee or an employee who has left. Ask each contact to confirm who can deploy and test the change. Look for low-volume endpoints that carry high-consequence work such as payment reconciliation, stock updates or scheduled file retrieval. Treat unknown callers as unresolved evidence rather than assuming they are obsolete. If identification is incomplete, improve logging of a non-secret client identity and ask known partners to identify their environments. This discovery sets a support plan and an honest migration window; it does not itself authorize an outage. Preserve a dated baseline of old-version usage so later claims of progress can be checked against the same definitions.

For a small order API, imagine three partners: one submits orders every minute, another downloads a settlement file each month, and a third has only a test environment. These are illustrative roles, not observed Astera clients. The minute-by-minute partner needs throughput and duplicate-order tests. The monthly partner needs at least one full settlement cycle on the replacement before the old export disappears. The test-only partner needs confirmation that no production credential or scheduled task still calls the old route. A single announcement or a dashboard showing falling total traffic would conceal these different risks. Build the migration register around completed business outcomes, not just successful HTTP responses.

Make the replacement a testable contract

Publish a migration guide that pairs each old operation with its replacement and states what changes in required fields, default values, identifiers, ordering, pagination, authentication, validation and errors. Say explicitly when a field has no direct replacement or when clients must change their own data model. Provide examples for both a normal request and a failure that the client must handle. Version labels alone are inadequate: an integration can receive a successful response while silently dropping a field used for invoicing. Where practical, keep the old and new versions running together for a measured overlap, but define the compatibility boundary so neither team expects the old service to gain every new feature.

Give clients a sandbox or test account whose data and limits are clearly distinguished from production. Agree on acceptance evidence: representative create, read and update paths; expected error handling; replay of a duplicate request where relevant; and a comparison of the resulting business records. Include boundary cases such as an empty result, a page after the first page, expired credentials and delayed upstream work. A partner that merely changes the URL in a test script has not demonstrated that its overnight importer or human exception queue still works. The owner should name who signs off each integration and retain test results without exposing real personal data in shared tickets. An agreed rollback path should say which version can be switched back and which records require reconciliation.

Plan communications as a sequence rather than a one-off warning. Send the change map and proposed dates to the owner and developer; invite acknowledgement; offer a test window; then report remaining old-version use to that specific client. Keep a route for a client to explain a genuine blocker, and set a decision owner who can extend a window when the evidence warrants it. Avoid promising that a retirement date is fixed if contractual notice periods or unresolved critical integrations can change it. Conversely, an indefinite old version creates an unbounded support obligation. Define criteria for choosing a date, publish changes to the plan, and keep the migration guide accessible after retirement for diagnosis and audit.

Use lifecycle signals accurately

The Deprecation response header defined in RFC 9745 tells a consumer that the resource has been or will be deprecated. It does not change the resource's behaviour. A deprecation link can point to human-readable migration documentation. The Sunset header in RFC 8594 has a different purpose: it signals an expected time when the resource may become unresponsive, using an HTTP-date value. Its timestamp is a hint, not a guarantee of availability until that instant or failure immediately afterward. These headers are useful machine-readable supplements, but a client may never inspect them; direct contact, documentation and change notices remain essential. Keep the announced dates, header values and documentation consistent.

Do not copy a timestamp from a tutorial into production. Choose a date only after checking contract notice, client deployment cycles, support capacity and the business season. Convert the chosen instant to a clear time zone in human notices and confirm that systems emit the correct header syntax. Test the headers on every affected response path, including error responses where clients may first notice trouble. Decide what the retired route will actually do: a documented error, redirect where safe, or another explicit response. The Sunset specification does not decide that behaviour for you. For non-idempotent requests, a redirect can change client behaviour unexpectedly, so test clients rather than assuming a redirect is a migration strategy.

Retirement is a release, not just a calendar event. Before changing production, compare recent old-version calls with the migration register, review unassigned callers, and verify that critical clients have completed their business cycle on the replacement. During the cutover, watch error rates and outcomes by client and operation, with a staffed path to investigate failures. Afterward, reconcile key records such as orders or settlement totals using the same business definitions used in acceptance testing. If an essential client was missed, the incident owner needs a pre-agreed choice between temporary restoration, a targeted exception or assisted migration. Record the decision and customer communication. Finally remove obsolete code and access only after evidence shows the planned dependency has ended.

A useful final rehearsal is to act as an unfamiliar partner. Start only with the published migration guide and a test credential; perform the full business journey, including a failed request, a repeated request and an end-of-day reconciliation. Note every place where undocumented knowledge from your own developers is needed. If the guide cannot explain whether a missing field means unknown, omitted or removed, a client may make a dangerous default assumption. Ask a support colleague who did not design the API to answer a sample migration question from the guide, then correct the document. This is also the right time to check observability: can support locate a client's failed call from a safe request identifier without seeing its secret? Can the client identify which version handled the response? Document the escalation channel and expected ownership of defects discovered during overlap. These concrete checks turn a proposed sunset into a service transition that a partner can actually execute.

Set explicit evidence for the final go or delay decision. The change owner should be able to show which production partners acknowledged the notice, which passed the replacement tests, which still made old calls in the latest observation window, and which exceptions have named owners and expiry dates. An exception should identify an affected operation and client rather than leave the entire old version open by default. If the retirement date moves, update the public guide and machine-readable signals together and tell affected partners what changed. After cutover, keep enough operational monitoring to detect a dormant job that wakes up later, especially one that runs monthly or quarterly. The old endpoint's low daily traffic is never enough on its own to prove safe removal. This decision record helps the business explain why it retired the version when it did and what it would do if a missed dependency appeared.