# A deprecated API can keep running, and that is the trap

> Moving a client from v1 to v2 without halting orders takes an adapter, parallel runs and close checks on write logic, where errors surface as bad data.

Original: https://fdetimes.net/en/guides/api-v1-to-v2-migration-without-downtime/

Picture a Monday morning at a client. The head of operations forwards you an email from a software vendor: API v1 will lose support on a specific date, and there is a link to a migration guide. The last line of the email is from the client: "Can you handle this? Orders can't stop."

The hard part is that nobody will let you take the system down to switch. Orders keep flowing, syncs keep running, and every mistake made during the switch shows up as wrong data rather than a clear exception.

One approach works straight away: detect early, wrap the calls in an adapter, run both versions in parallel, shift over gradually, and recheck exactly the places that tend to break.

## The deprecation date is not a safe deadline

Many engineers' first instinct is to put the shutdown date in the calendar and count back a few weeks. Webflow's deprecation notice for v1 shows why that thinking is dangerous: after the date, v1 may still work, but it will no longer be maintained, updated or supported.

**Key point:** A deprecated API can keep running, and that is exactly the trap.

An API that "still works" but that nobody is responsible for is the worst kind of risk. It can break at any moment, and when it does there is nobody to file a ticket with. That is why Webflow advises customers to start migrating as early as possible so their integrations are not interrupted.

It also helps to understand why vendors do this. Stripe itself acknowledges that backward compatibility is not free: every new version adds code that has to be understood and maintained. Not every vendor is willing to carry that cost for long, so the shutdown date is something to plan for in advance.

## Let the system warn you before the email arrives

Emails get missed. HTTP headers do not. RFC 9745 defines the `Deprecation` header to tell callers that a resource will be, or already has been, deprecated. If the vendor also sends a `Sunset` header, its timestamp must not be earlier than the one in `Deprecation`, so the deprecation notice always comes before the shutdown.

The RFC also allows a pointer to documentation through a `Link` header with the `deprecation` relation. Not every vendor sends these headers, but logging them costs almost nothing. Put this in the client's shared HTTP client:

```python
import logging
import requests

log = logging.getLogger("vendor_api")
BASE = "https://api.vendor.example"

def call(method, path, **kw):
    resp = requests.request(method, BASE + path, timeout=10, **kw)
    if "Deprecation" in resp.headers or "Sunset" in resp.headers:
        log.warning(
            "deprecated endpoint %s %s deprecation=%s sunset=%s link=%s",
            method, path,
            resp.headers.get("Deprecation"),
            resp.headers.get("Sunset"),
            resp.headers.get("Link"),
        )
    return resp
```

After a week, the log gives you a list of endpoints that are actually being called and have been marked as deprecated. That list is more reliable than any manual inventory, because it comes from production traffic.

## Example: syncing order status

Suppose the client has a service that pushes order status updates to the vendor's system. In v1 the only option is to read the whole record, change one field and overwrite the whole record. The v2 documentation is explicit, much like Chainguard's migration guide: replace fetch-modify-write logic with a PATCH call that sets only the fields that change.

That detail matters more than changing `/v1/` to `/v2/`, because it touches the write logic: every place in the code that sends data to create or modify a record.

With fetch-modify-write, if two processes edit the same record, the later write can wipe out the earlier one's changes. Moving to PATCH changes how writes work, and every place in the code that implicitly relied on "rewrite the whole record" has to be reviewed.

So the first step is to route every call through a single adapter and decide which version to use in exactly one place:

```python
import zlib

V2_ROLLOUT_PERCENT = 5  # increase gradually: 5 -> 25 -> 50 -> 100

class VendorError(Exception):
    @classmethod
    def from_v2(cls, resp):
        # v2 returns errors in a new format: parse error code and message per the v2 docs
        return cls(f"{resp.status_code}: {resp.text}")

def use_v2(order_id: str) -> bool:
    return zlib.crc32(order_id.encode()) % 100 < V2_ROLLOUT_PERCENT

class OrderStatusClient:
    def update_status(self, order_id, status):
        if use_v2(order_id):
            return self._v2_patch(order_id, status)
        return self._v1_fetch_modify_write(order_id, status)

    def _v1_fetch_modify_write(self, order_id, status):
        item = call("GET", f"/v1/items/{order_id}").json()
        item["status"] = status
        return call("PUT", f"/v1/items/{order_id}", json=item)

    def _v2_patch(self, order_id, status):
        resp = call("PATCH", f"/v2/items/{order_id}", json={"status": status})
        if resp.status_code >= 400:
            raise VendorError.from_v2(resp)
        return resp
```

Hashing on `order_id` keeps each order on the same version, so you never mix two styles of write on one record. This only works when the vendor runs both versions in parallel. Chainguard is an example: v1 and v2 run side by side, customers can migrate piece by piece, and no shutdown date was set at launch.

Some vendors allow even finer control. Stripe pins each account to a version but lets you override it per request with the `Stripe-Version` header.

That means you can try the new version on a single call before switching everything. If the API you are integrating with has a similar mechanism, use it for the first 5% stage.

## The real breakage is in the error paths

The happy path usually works first time, which is why many teams declare victory too early. Chainguard's guide warns about exactly this: v2 changes the error format and status codes, so the error-handling paths need retesting, not just the happy path.

Think about the client's retry code. If it matches a string in the v1 error body to decide whether to retry, that string disappears in v2. The result: transient errors are not retried, or permanent errors are retried forever. Nothing crashes; orders just sit quietly in the wrong state.

## The sequence at the client

Start by logging headers for a week to get the real list of endpoints. Next, read the migration guide and flag every behavioural change, especially in how writes work and how errors are returned, because those need rewriting, not just a path change.

Then build the adapter, write tests for both branches and turn v2 on at 5%. Watch the error rate and compare data between the two groups of orders before increasing. Delete the v1 code only once v2 has run at 100% long enough to cover weekly and monthly jobs too.

In parallel, write the client a short page: what has changed, the current rollout percentage, and how to fall back to v1 if something goes wrong. Operations staff do not need to read the code, but they do need to know who pulls the rollback lever and when.

## Common mistakes

The most common mistake is treating the deprecation date as the shutdown date and waiting until the last minute. The second is leaving API calls scattered across the codebase, which makes a gradual switch impossible and forces everything to change at once. The third is testing only the happy path, as described above.

A less discussed mistake is forgetting the side scripts: cron jobs, analysis notebooks, an internal tool someone wrote two years ago. They do not go through your adapter, so if the client has a shared proxy or gateway, log deprecation headers at that layer too so nothing slips through.

When you describe this migration on a CV or in an interview, a line such as "migrated integration X from v1 to v2 by traffic share with zero downtime, rewriting write logic to PATCH" says more than a list of technologies, especially if you can go on to describe the error paths you caught.

More deprecation emails will come, from this vendor or another. If the adapter and header logging are already in place, next time you only need to change one file, and the client will never know anything happened.

**Try this week:**

- Add a warning log line to the client's HTTP client whenever a response carries a Deprecation or Sunset header, then check which endpoints show up after 7 days.
- List every place in the codebase that reads a whole record and then overwrites the whole record, and flag the ones that will need changing once the new API supports PATCH.
- Write three tests for the error paths (400, 404, 429) of an integration you own and run them against both API versions.

## Sources

- [RFC 9745: The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745.html)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [Webflow v1 API Deprecation Notice](https://developers.webflow.com/data/v1.0.0/docs/webflow-v1-api-deprecation-notice)

- [Migrating from API v1 to API v2](https://www.chainguard.dev/docs/platform/api/api-v2-migration/index.md)
