Change an API version without overlooking the data flow

Plan a change to an application programming interface (API) around the affected data flows. The new endpoint is only part of the migration: fields, permissions and response handling must also fit the calling system.

Identify the affected callers

In a fictional company, a customer portal and a nightly import send orders to the same API. Migrating only the portal would leave the second caller behind. Record which functions each caller uses and who can carry out its migration. Use the actual provider's change and shutdown information; a version number does not establish a universal migration deadline.

Google AIP-180 distinguishes source, wire and semantic compatibility. The guidance helps assess changes; it does not guarantee the behaviour of an arbitrary third-party API.

Describe the change with a worked example

In our example, the old request carries text in the delivery_note field. The new version expects the text under delivery_note.text. Both must carry the same delivery instruction, “Tor B”. Replacing a URL or successfully connecting is therefore insufficient for this migration.

Also check how errors and processing still in progress are reported. A different response structure can affect the caller even if the request continues to be accepted.

Compare old and new under the same conditions

In a suitable test environment, prepare a normal order and a case with a missing delivery instruction. Compare the stored target data and the visible response. Also establish whether the access permissions in use cover both versions. Real orders should not be sent down two production paths for this comparison.

Coordinate the switch with open operations

Specify the point from which new requests use the new path. Requests already sent but still unconfirmed need a mapping so that a retry is not treated as a new order. Agree a fallback path for newly arriving requests and separately assess what happens to data already written. Reverting a URL does not undo those changes.

The old version can be removed from this data flow once all recorded callers have migrated and open operations have been mapped. Document the state actually checked rather than just the new version label.

Sources

• Google AIP-180: Backwards compatibility