Changing API gateway is rarely a project one chooses for pleasure. The triggers we encounter are more prosaic: end of support for a version, a licence renewal, a reversibility requirement, consolidation after a merger, or a wish to regain control of a component that has become critical. Whether one is leaving a vendor product or a managed service, the constraint is the same: consumers must notice nothing.

This article describes the method we apply. It depends neither on the gateway of departure nor on the one of arrival.

The real scope: the contracts, not the configuration

The classic mistake is to treat the migration as a configuration conversion: the APIs are exported from the old gateway, translated, and imported into the new one. What consumers use, however, is not the configuration; it is a contract, in the broad sense:

  • the URL, the paths, the methods and the request and response formats;
  • the authentication mode and the shape of tokens or keys;
  • error codes and the format of error messages;
  • headers added or removed by the gateway;
  • traffic limits and behaviour when they are exceeded;
  • timeouts, maximum message size, handling of special characters.

Part of this contract is written nowhere: it results from the default behaviour of the old gateway. It is precisely this implicit part that breaks during migrations.

Step 1: inventory what is actually used

Before migrating anything, one needs to know:

  • which APIs are called, by whom, and how often;
  • which versions are still in use;
  • which authentication modes are in service;
  • which APIs are no longer called at all.

The current gateway’s logs and statistics are the main source. This inventory almost always has a useful side effect: part of the catalogue can be retired instead of being migrated. The share concerned is determined case by case, from actual usage.

Step 2: write down the implicit contract

For each API being migrated, the observable behaviour of the old gateway is captured: nominal responses, error responses, headers, behaviour under a traffic limit. The most useful form is an executable contract test suite that can be run against any gateway:

  • it is first run against the old gateway, to check that it describes reality;
  • it is then run against the new one, and every discrepancy is either corrected, or accepted explicitly and communicated to consumers.

This is the heart of the method: the migration is finished when the suite passes on the new gateway, not when the configuration has been imported.

Step 3: separate intent from format

Rather than translating format A directly into format B, we describe each API in a neutral format (an OpenAPI or WSDL contract, a readable description of policies, per-environment values), versioned in Git. The deployment layer then translates it to the target gateway.

This detour costs a little at the beginning, but it pays twice: the migration becomes reproducible, and the next migration — because there will be one — starts from a product-independent base.

Step 4: let the two gateways coexist

A “big bang” cutover on a weekend is the riskiest method. We prefer to let the two gateways coexist behind a common entry point (a load balancer, DNS or upstream routing):

  1. the new gateway is deployed, the API is configured on it, the contract suite passes;
  2. a small share of traffic, or a willing pilot consumer, is directed to the new gateway;
  3. one observes: error rate, latency, behavioural discrepancies;
  4. the share is increased gradually, API by API or consumer by consumer;
  5. the old gateway remains ready to take the traffic back for as long as the cutover is not confirmed.

This coexistence requires two delicate points to be anticipated: identities (keys or OAuth clients must be recognised by both gateways during the transition) and quotas (a consumer split across two gateways must not see its limit doubled or halved unless that has been decided).

Step 5: plan the rollback, and test it

Every cutover step must be reversible quickly, by the same mechanism that triggered it: a routing change, not a reinstallation. A rollback that has never been exercised does not exist. We test it deliberately in staging, then at least once on a real, low-stakes scope.

Step 6: communicate with consumers

Even a successful migration can surprise a consumer who depended on an undocumented behaviour. What helps:

  • inform consumers before each wave, with an identified counterpart;
  • publish accepted discrepancies (for example a slightly different error format) before they are discovered in production;
  • offer an environment where consumers can test against the new gateway.

Frequent pitfalls

  • Migrating dead APIs. The inventory avoids carrying debt forward.
  • Forgetting default behaviours. Timeouts, maximum sizes, encodings: they are part of the contract.
  • Changing gateway and contract at the same time. One migrates first at a constant contract, then evolves it. Mixing the two makes every discrepancy impossible to attribute.
  • Underestimating identities. Migrating keys, OAuth clients and certificates is often the critical path.
  • Decommissioning too early. The old gateway remains available, at least in read-only form, until complete confirmation.

What to take away

A successful gateway migration is measured by what consumers do not see. To get there: inventory what is actually used, write the implicit contract as tests, separate intent from format, let the gateways coexist, and never cut over without a tested rollback. The choice of the target gateway matters, but less than the method.

Alongside its consulting work, CAB Ingénierie develops STOA, a sovereign iPaaS and API integration platform.

Let's talk about your project

Are you preparing a gateway change, or do you want to assess what it would cost? Tell us about your context in a few lines: cab-ingenierie.com · contact@cab-ingenierie.com