API changes: explain client impact and migration

Last updated: 2 Oct 202611 min read

tutorial

An API change prompt should describe the before and after contract, supported versions, affected clients, rollout timing, and test evidence. Adding an enum value can look additive in a schema while breaking clients with exhaustive status handling. The prompt should ask how callers treat unknown values and whether a versioned migration note is required. Record the old behavior, new behavior, fallback for clients that cannot update immediately, and owner of each compatibility claim. Do not announce a deprecation or date unless the release policy approves it. A migration note is a change guide, not a substitute for the current operation page.

Operational case

Shipment Status v2 adds held. One client maps every known status to an icon with no default branch; held causes that client to fail despite being an added enum value. Another client displays unknown statuses as 'Status unavailable' and continues. The prompt documents both outcomes and asks the API owner whether to gate held behind a version boundary or coordinate the client release. The draft migration note tells callers to handle unknown status values and adds a held fixture to contract tests. It does not claim that every client is safe because the response still uses a string.

Before: queued | in_transit | delivered.
After: queued | in_transit | held | delivered.
Client A: exhaustive mapping -> fails on held.
Client B: unknown fallback -> remains usable.
Gate: choose version/release plan; add held contract fixture.
Do not invent deprecation date or universal compatibility.

Performance and operating cost

With C known client integrations and S changed status values, targeted compatibility review is O(CS) behavior checks. Unknown external clients add uncertainty; publish a conservative migration note and monitoring plan rather than claiming total coverage. A coordinated release may slow delivery, but it avoids turning an apparently harmless schema addition into a client outage. Keep version and behavior claims tied to the actual deployment state; a merged contract change is not proof that every environment serves held.

Common Mistakes

Do not equate additive schema shape with safe client behavior.
Do not promise a retirement date the release plan has not approved.
Do not report held as live in every environment from a merged test alone.

Connected lessons

prompt engineering

api documentation