Define what the decision needs
Consider a replenishment planner that reads a provider inventory feed. For this example, its contract requires a named account, warehouse, and product; a supported contract version; a nonnegative integer quantity in individual units; and the time that inventory was observed. The planner accepts observations at most five minutes old. Those are example requirements chosen for this decision, not claims about a particular provider.
An HTTP success and a parseable JSON object leave much of that rule unchecked. Compare the returned identity with the expected identity held by the request owner. A quantity for another warehouse cannot become a missing-product result. Treat a wrong account or resource as an integrity failure, stop automatic use, and give the integration owner enough redacted evidence to investigate. Keep that distinction visible through caches and downstream adapters.
Allow extensions without inventing meaning
Version selection reduces ambiguity, but its exact promise comes from the provider. GitHub documents that additive changes, including response fields and enum values, can reach every supported REST API version. Pinning a GitHub API version therefore does not freeze the complete response shape. Read the actual provider policy before deciding which changes the adapter should tolerate.
For the inventory example, an extra descriptive field can be ignored if it has no role in the acceptance rule. An unfamiliar availability state needs a different decision when that state determines whether stock can be allocated. Preserve it as an unsupported state until someone establishes its meaning. Do not map it to available, unavailable, or zero quantity merely to keep the parser returning a familiar type. Validate units and numeric bounds before constructing the internal inventory value.
Measure the age of the underlying observation
Suppose the decision time is 12:10 UTC and the provider says inventory was observed at 12:02 UTC. The observation is 480 seconds old, exceeding the example limit of 300 seconds by 180 seconds. Fetching that response at 12:10 does not change the observation time. With the same assumed clocks, an observation at 12:06 is 240 seconds old and passes the age test. Identity and meaning must still pass their own checks.
RFC 9111 defines HTTP Age around when a response was generated or validated at the origin. That does not establish when a warehouse counted its stock. A newly generated response can contain an older business observation. Keep fetched time, HTTP cache metadata, and provider observation time as distinct facts. Confirm the timestamp semantics: a last-change timestamp cannot automatically substitute for evidence that unchanged stock was recently observed.
A missing observation timestamp leaves freshness unresolved under this contract. A timestamp in the future also needs investigation of clock uncertainty and timestamp meaning. Avoid silently treating it as zero age. Choose and document the acceptable clock uncertainty with the provider before using a timestamp near the freshness boundary.
- Expected scopeBind the request identity
Carry the expected account, warehouse, product, and contract version into validation.
- MeaningValidate the representation
Check identity, supported states, units, and numeric bounds before creating an inventory value.
- Observation ageApply the freshness rule
Evaluate the provider observation timestamp against decision time and the agreed clock assumptions.
- DispositionAccept or hold the decision
Preserve stale, unresolved, contract, and integrity failures for the owner who can resolve them.
Keep fallback behavior within the same contract
Separate provider unavailability, unsupported representation, wrong identity, and stale observations in the adapter result. They call for different responses. Repeatedly fetching a response with incompatible units does not establish a conversion rule. A last-known value for another account is never an acceptable substitute for this request. Include all required identity and representation dimensions in the application cache key.
A previously accepted value can be considered only while it still meets the current use policy. Recalculate its observation age at the decision time. If the replenishment rule requires stock no older than five minutes, an older cached value cannot silently extend that allowance. A separate display policy might permit dated historical information, but the automated planner must receive an explicit hold when its own requirements are unmet.
Give the canary a response owner
Stored fixtures exercise the cases already captured. A scheduled live canary adds evidence about a selected provider path now. AWS describes canaries as scripts that follow customer routes and actions to check endpoints. For this integration, choose a permitted read-only account and representative resource, with a fixed scope, request deadline, and rate budget. Run the production adapter and acceptance rule against the result.
Assign the integration team ownership of the canary, the acceptance policy, and the response to failure. Retain the requested scope, selected version, validation outcome, observation time, and a redacted diagnostic reference. Track the last completed check separately from the last accepted observation. Alert when the check stops running as well as when it returns unusable data. Route an integrity failure differently from an expired observation so the first responder has a concrete action.
Google SRE includes HTTP 200 responses with incorrect content among service errors. The canary must therefore inspect the facts the planner depends on. A successful check applies to the endpoint, account, resource, and time it covered; it cannot certify every provider response. Keep validation on the ordinary consumption path, and expand canary coverage when a distinct representation or business rule warrants another case.
Prepare a reviewable acceptance decision
Before adopting a provider change, retain representative old and new responses, the documented version policy, and the expected disposition for each changed field. Include cases for wrong identity, unfamiliar states, stale data, and missing freshness evidence. The review should identify who can change the five-minute requirement and who responds when the provider cannot meet it. These artifacts make the proposed acceptance rule inspectable before it governs an automated business decision.
