When an upstream API changes fields: detect the impact and plan the transition

Do not wait for a broken screen to discover that an upstream API changed. Maintain a record of the fields and meanings your software actually relies on, obtain change notices and samples, validate the resulting reads and writes, and then switch within an agreed compatibility window. An API can continue returning successful responses while changed amount units, status meanings or pagination rules produce incorrect business results.

Record what your application actually depends on

You do not need to duplicate the provider's entire API manual. Start with the operations and fields your software consumes, their direction, authentication, business purpose and responsible owner. Record where each field is used. An order status may control list styling, approval decisions, exports and reporting filters. Repairing the list alone can leave the other consumers wrong.

For each dependency, retain the API version, field type, permitted null conditions, enum meanings, monetary units, timestamps and time zones, pagination and data update point. Extend the system integration responsibility model with the people who issue notices, provide samples and approve the transition. This connects the initial API deliverables in custom software development (Chinese) to ongoing maintenance.

Use two checks to detect responses that succeed but are wrong

Check structure and missing values first

Compare test responses with the agreed contract to find removed fields, changed types, additional required inputs, new enum values or a previously complete list becoming paginated. Keep samples for normal results, nulls, access denial, no records and multiple pages. An unfamiliar status needs an explicit handling path; it should not silently become “completed.” Missing monetary values should not turn into zero and flow unnoticed into totals.

Then verify business meaning

Choose a record involving cancellation, a refund or a change across business dates. Compare the page, export and aggregate results before and after the upgrade. A field still called “amount” might change from tax-inclusive to tax-exclusive, while an unchanged-looking timestamp could use a different time zone. Checking that a field exists will not reveal those changes.

Google AIP-180 on backwards compatibility includes semantic compatibility and identifies renaming, field-type changes and changes to default behavior as potential breaks for existing clients. It is design guidance, not an assurance that an ERP supplier follows those rules. Establish the actual contract and notification channel with the provider.

Choose a transition method the upstream service can support

• If both versions can coexist, connect the new version for read-only comparison first. Define the comparison period, difference owner and retirement date for the old version. Avoid duplicating write operations during the trial.
• If both parties must upgrade together, reserve the integration environment, release time and affected write restrictions. Complete sample regression before the maintenance window and keep an agreed manual handling route available.
• If no test version is available, record what can be verified and what remains unknown. Arrange launch-day observation, stop conditions and support ownership. Do not describe an untested assumption as confirmed compatibility.

There is no universal length for a compatibility window. It needs to cover the actual changes, deployments and business confirmation on both sides. An adapter can translate formats, but it cannot infer missing business meaning. A changed monetary definition needs a decision from the data owner, not a guess embedded in conversion code.

Trace acceptance to downstream results and rollback limits

Before switching, preserve old and new samples, mapping rules and test evidence, including the environment and version used. Afterward, monitor more than response failures. Inspect the agreed records for missing fields, unfamiliar statuses, data freshness and business totals. A series of successful HTTP responses is not proof that the content is correct.

Restoring an old query destination is usually simpler when the new version has only been used for reads. Once it has created or changed business records, establish whether the old version can interpret them and whether compensation is needed. Changing the API address back and resubmitting requests with unknown outcomes can create further inconsistencies. Define rollback triggers, the operator and records needing manual reconciliation before release.

The acceptance package should include affected functions, version and field differences, positive and negative samples, transition records and unresolved limits. Use the post-launch maintenance scope to classify third-party upgrades, define what happens if notification fails, and determine whether additional fields require separate assessment. A general promise of “API maintenance” does not replace those responsibilities.