BlogAPI designUpdated

An API version belongs with the code

Move a consumer from API 2.0.0 to 2.1.0 with explicit request pins, matching field readers and an offline Carrier adapter example.

An API upgrade changes the code that reads its responses. Keep the request version and the field reader with the same application release, so you can test the change before switching callers.

The key identifies the team. The X-API-Version request header declares the contract the application expects. The X-API-Version response header reports the exact effective version. Changing a request pin does not replace the key, change the team's saved default, or grant another allowance.

Change the request and reader together

API 2.1.0 puts optional profile facts at their natural resource paths. A paid Country profile uses result.population, for example. Paid plans include their existing profile detail by default. HTTP deep=true can still request that detail explicitly, and HTTP deep=false selects the basic response. The response has no object named deep.

Carrier and HLR return their complete selected metered results without a Deep option. Email verification is explicit GET /email/verify, whose result includes the basic validation fields too.

For Carrier, a migration from 2.0 to 2.1 looks like this:

Application releaseRequest pinDetail optionState reader
Earlier2.0.0?deep=trueresult.deep?.state
New2.1.0None neededresult.state

The issuing state is numbering-plan context, not the subscriber's current location. The selected Carrier lookup keeps its existing allowance rules. Including its available location fields does not purchase another check.

These illustrative excerpts show the fields used by the example consumer. They are not complete responses or observations about a real phone number. The earlier 2.0 response excerpt is:

{
  "valid": true,
  "carrier": "Example Carrier",
  "burner": false,
  "deep": { "state": "CO" }
}

The 2.1 excerpt is:

{
  "valid": true,
  "carrier": "Example Carrier",
  "burner": false,
  "state": "CO"
}

A returned state: null means the selected check has no known state. Keep null separate from a missing property and keep burner: false separate from an unknown burner result.

Test the application view offline

Download the contract rollout example, then run it with Node.js:

node --test api-contract-rollout.mjs

It has no dependencies to install, reads no key and makes no network requests. It retains the earlier adapters for migration tests and adds a 2.1 reader. The two application views should agree:

const oldView = adaptCarrier20(
  fixtureResponse('2.0.0', fixtures.current)
);
const newView = adaptCarrier21(
  fixtureResponse('2.1.0', fixtures.natural)
);
assert.deepEqual(oldView, newView);

Those adapters belong to the example application. They are not separate SDK clients. SDK packages that target API 2.1 use the existing factories and methods. New SDK releases target API 2.2; previously installed packages keep their documented contracts. The 2.1 migration shown here requires updating old .deep property reads.

The example also tests unknown values, invalid input, errors and mismatched response versions. HTTP errors remain errors rather than becoming synthetic lookup results. A version-selection error may occur before an effective version can be echoed, so handle status and error code before reading a success model.

Keep a pin with each application build

Before changing an existing integration, determine its effective version and pin it explicitly. During migration, one build can send X-API-Version: 2.0.0 while the updated build sends X-API-Version: 2.1.0. Test the outgoing request header as well as the body reader.

The team default governs requests that omit the header. Keep it stable while other applications or a rollback build rely on it. An explicitly pinned application does not need a dashboard change to migrate.

Rollback restores the earlier application code together with its pin or dependency lockfile. It depends on that earlier contract remaining supported. Existing API contracts are a temporary migration bridge. The SDKs have one maintained path forward.

Package versions and API versions have different jobs. Keep the SDK package locked with the application and read its upgrade notes. A package number does not identify an API contract by itself.

A contract pin does not freeze the data

Versioning preserves the response contract. It does not freeze weather observations, carrier facts or maintained reference data at the date of adoption. Keep observation dates when an operation supplies them, and do not treat a request's version as a data timestamp.

The 2.1 release notes and versioning guide describe the migration. A versioned reference such as https://api.parseapi.com/version/2.1.0/carrier/help describes that contract. Lookup requests select their contract with the request header.