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.
In brief
- v1 may keep working after the deprecation date but will no longer be supported, so do not treat that date as a safe deadline.
- Route every call through one adapter, run v1 and v2 side by side and shift traffic over gradually with a flag.
- The parts most likely to break are the write logic (fetch-modify-write becoming PATCH) and the error format, not the URL.
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.
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:
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:
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 find-and-replace migration
- Find and replace /v1/ with /v2/
- Run the happy-path tests
- Switch 100% in a single deploy
- Find the bugs when the client complains
The zero-downtime migration
- Build the endpoint list from deprecation-header logs
- Review every place the code writes data, especially full-record overwrites
- Retest every error code and the retry logic
- Shift gradually behind a flag, with a way back to v1
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.
Was this article useful?
Thanks for the feedback!