Migrations

Migrating an API integration is mostly not a code problem. The request changes in three places — the host, the auth header, the response shape — and the rest of the work is proving the new answers match the old ones before anything depends on them.

If you are coming from somewhere not listed, the sequence below still applies. The specifics you need are on making requests and response format.

The order that works

1. Find the endpoint that replaces yours. Search the catalog. Read the reference page and compare its response fields against the ones your code actually reads — not the ones the old provider documented, the ones you use. This is where migrations go wrong: a field you assumed was universal turns out to be that provider's invention.

2. Call it once, by hand. Before touching your code, run the request from the playground or with cURL and look at the real response. Free credits cover this comfortably.

3. Write an adapter, not a rewrite. Put the new call behind the same function signature your code already uses and map the response into whatever shape the rest of your application expects. One function changes; nothing else does.

4. Run both and compare. Call the old provider and the new one for the same inputs and log where they disagree. A day of this on real traffic tells you more than any amount of reading, and disagreements are usually informative rather than alarming — different providers genuinely resolve some inputs differently.

5. Cut over behind a flag. A boolean that picks the implementation, defaulted off, flipped when the comparison is clean. It also gives you an instant rollback that does not require a deploy.

6. Remove the old path once you have gone a full billing cycle without touching it. Not before — a flag you never remove is technical debt, but a flag you remove too early is an outage.

What changes in the code

One host. https://api.apiverve.com/v1/<endpoint>. Not a host per API.

One header. x-api-key. No second header naming which API you are calling, and no per-endpoint credential.

One response envelope. Every endpoint returns status, error and data, with the result inside data. That means one response handler for your whole integration instead of one per provider:

const res = await fetch(`https://api.apiverve.com/v1/${endpoint}`, {
  headers: { 'x-api-key': process.env.APIVERVE_API_KEY },
});
const body = await res.json();

if (body.status !== 'ok') throw new Error(body.error);
return body.data;

Check status, not the presence of fields inside data. A lookup that legitimately found nothing is a successful call with an empty result — see response format.

One error vocabulary. 400 names the parameter that is wrong, 401 means the key is not valid, 403 means the key is real but not allowed to make this call, 429 means the rate limit or an empty balance. Error handling covers each.

Things worth doing while you are in there

A migration is the one moment when touching this code is already budgeted, so:

Issue a sub-key per environment instead of putting one key everywhere. Staging and production having separate, individually revocable credentials costs nothing now and is awkward to retrofit later.

Scope the key to what it calls. You know exactly which endpoints the integration uses, because you just wrote them down.

Set the usage alert in settings before you cut over, not after the first surprising bill.

Retry on 429 and 5xx, never on 400. Migrations are when retry logic gets written, and a blanket retry spends credits re-sending requests that were malformed the first time.

Testing without spending

Two ways to build against responses before you commit real calls:

Mock endpoints return a response you define, at a URL you control, for nothing. Useful for wiring up the unhappy paths — your error handling needs a 400 to be tested against, and provoking real ones is wasteful.

The Postman collection has a mock mode that returns example responses for every endpoint with no key and no credits, which is a fast way to see the shape of a hundred responses while you are deciding what to map.

Getting help

Migration support is free. If an endpoint looks like it should replace yours but the fields do not line up, ask rather than building an adapter around a mismatch — sometimes the field you want exists under a different name, and sometimes we can add it.

Next

RapidAPI is the worked example. Making requests is the request in full.