Skip to main content

API compatibility assessment and calibration

Attempt independently before calibration. Score 0 absent/incorrect, 1 prompted/incomplete, 2 independently correct with evidence and limits, 3 successful transfer. Every category requires at least 2. Model checks do not substitute for real consumer, transport or persistence evidence.

Required evidence​

  • AC1 — Direction: classify request and response changes separately and provide witnesses for required-field addition, enum changes and strict-reader field addition.
  • AC2 — Implementation: implement the finite archive contract, retain three independent schema pairs and prove an empty object is not confused with no witness. Preserve original attempts and repairs.
  • AC3 — Semantic behavior: demonstrate unchanged schemas with changed meaning/default/order; add a real consumer test that fails. State which compatibility claims the checker cannot make.
  • AC4 — Migration: execute supported old/new consumer/provider combinations over the original HTTP API, retain fixtures and perform rollback. Keep the OpenAPI contract, migration timeline and usage-telemetry/removal policy.
  • AC5 — Retry: demonstrate response loss after commit, concurrent retry, payload conflict, restart and expiry behavior with durable handling. Document identity scope and request fingerprint; compare observed outcomes with promises.
  • AC6 — Consumer review: have another learner use only the documentation, preserve their failure/ambiguity log and repair the contract. If independent review is unavailable, record this category as incomplete rather than substituting your own successful test.

Fresh defense​

After at least 48 hours, compare unseen schemas and a changed retry-expiry policy without the reference. Explain the rollback consequences of a newly required field. Disclose assistance and repair any category below 2 before progression. Preserve original REST/gRPC comparison, integration-style reasoning and deprecation playbook.

Calibration — open after attempting​

Widening accepted request values preserves old requests; widening possible response values may break an old reader. Making an optional request field required creates a missing-field witness. Making a required response field optional may emit an object the old consumer cannot read. Additional response fields break this lab's strict closed-object consumer; a tolerant policy requires separate evidence.

The empty object is a real request witness when the new server adds a required field. None alone means no witness in the model. A schema allowing only an empty-string value still requires a present field when marked required; absence and empty string are different.

Changing cents to dollars can preserve shape while breaking meaning. Old-client/new-server success says nothing about new-client/old-server rollback. Durable duplicate handling must survive the modeled restart and serialize concurrent identities; a successful sequential mock does not establish either property. Expired keys require explicit semantics and may no longer suppress an old replay.

Independent consumer feedback is a separate requirement. Author reference tests and a documentation-only self-test do not demonstrate that another learner can integrate successfully.