Track changes to the API contract

Pin the OpenAPI document your integration was tested against and compare it with the next document before updating a generated client. A successful schema download does not establish that your integration still behaves correctly.

The developer site's API reference is generated from a stored OpenAPI snapshot. The live API and that snapshot can represent different revisions. The OpenAPI info.version value alone is not a reliable release identifier; store the download time and a content hash as well.

Use the public OpenAPI document. This endpoint needs no API key. Each example prints the document; save the output to a new timestamped JSON file rather than overwriting your last tested baseline.

curl --fail-with-body --silent --show-error --max-time 30 --globoff \
  --request GET 'https://cloud.campai.com/api/openapi.json'

Record the source URL and download time with the saved file. Use your version-control system to compare snapshots. If you compute a content hash, remember that reordered properties or changed examples can alter it without changing runtime behavior.

Maintain an inventory containing each operation ID, method, path, required permissions, request fields, consumed response fields, and a representative test. For example, the first-request guide depends on Get API key info, and receipt filtering depends on List receipts.

Compare these parts of the contract:

• Removed operations or changed method/path pairs.
• New required parameters, changed parameter locations, or changed authentication.
• Request property types, nullability, enum values, defaults, and validation limits.
• Response fields your code reads, including their types and optionality.
• Referenced schemas under components, not just the text inside the operation.

An unchanged operation object can still reference a changed component schema. Resolve references when comparing. Conversely, a new optional response field should not break a client that ignores fields it does not use.

OpenAPI cannot fully describe every selection rule, default scope, side effect, or product workflow. Inspect the corresponding implementation and run a behavioral test for the features you depend on.

Examples from these guides include the event date filters using period.to, userFilter being a JSON-encoded string, and app simulation making real API calls. Those details require more than checking whether a property exists in a schema.

Use recorded, synthetic fixtures for stable regression tests. Compare meaningful outcomes rather than the entire serialized response when the API can legitimately add fields or update timestamps.

Regenerate clients in a reviewed change. Compile your integration, run request and response fixtures, then run the relevant read checks and designated write-fixture checks against the intended environment.

If your application exposes a smaller API to a website or another service, keep that boundary stable. Map campai's response into your own documented projection so a new upstream field does not automatically become public data.

Keep the previous tested snapshot and client available for investigation. A rollback of your code does not roll back campai's server, so verify compatibility rather than assuming an old client will always recover service.

For each changed operation, record a compact comparison:

Review item	Before and after evidence
Request	Method/path, required fields, and enum values your client sends.
Response	Fields your projection reads, including missing versus null.
Access	Required permission and mandate selection.
Test	One known success, empty result if applicable, and a representative error.
Release decision	Compatible, needs an adapter change, or blocked by unresolved behavior.

Ready to update: every operation your integration uses has a decision and passing tests against the new contract. A successful specification download alone does not complete this check.

Store the source URL, timestamp, hash, changed operations, tests run, and their outcomes. Distinguish a contract-only check from a live request and from an end-to-end workflow test. A stubbed 200 response must not be reported as a successful live integration test.

If the saved contract differs from the live API, record the changed operations and verify them before updating your integration. Do not substitute an undocumented endpoint to make a test pass.