Versioning & deprecation
How the API evolves within v1 (additively), what a breaking change looks like, and the signals we send before removing anything.
The AirCredit Partner API is versioned in the URL path (/v1/…). Within a version we only ever
evolve additively; anything that could break a well-behaved client ships as a new URL version.
What "additive within v1" means
Inside /v1, any of these can appear at any time, without notice, and are not breaking:
- New fields on existing responses.
- New enum values — new
SubmissionStatus,UploadFailure.code,EventType,ApiErrorCode, and so on. - New event types delivered to endpoints subscribed to all events.
- New endpoints and new optional request parameters.
Your integration must tolerate all of the above. Concretely, a well-behaved client:
- Ignores unknown JSON fields rather than failing to deserialize.
- Tolerates unknown enum values — map anything you don't recognize to a safe default and keep going (for error codes, fall back to the HTTP status class; see Errors).
- Ignores unknown event types instead of erroring on them.
Tip
The generated SDKs are built to be lenient by default — unknown fields are preserved or skipped, not fatal. If you hand-roll a client, replicate that leniency.
Catalog enums vs lifecycle enums
The spec distinguishes two kinds of enums, with different growth expectations:
- Catalog key enums — the builtin template, document-type, check, and data-field keys. These are enumerated in the spec (and the SDKs) so you can match on them, but the catalogs grow within v1 as AirCredit ships new builtin content. The generated SDKs preserve unknown keys instead of failing; always keep a fallback arm.
- Lifecycle and status enums —
SubmissionStatus,UploadStatus, verdict statuses, error codes. These are stable vocabularies; they too may gain values additively (as listed above), but only deliberately and with a changelog entry — never as routine content growth.
What counts as breaking
These are the changes we will not make within /v1. They only ship under a new URL version
(/v2):
- Removing or renaming a field, endpoint, or enum value.
- Changing a field's type or its meaning.
- Making an optional request field required.
- Tightening validation in a way that rejects previously-accepted input.
Deprecation signals
Before anything is removed in a future major version, we signal it ahead of time:
- Documentation — the field, endpoint, or value is marked deprecated in the reference with the replacement and a timeline.
- Advance notice — deprecations are announced in the Changelog well before the cutover, never same-day.
- Overlap — the new version runs alongside the old for a migration window; you are never forced to cut over instantly.
Treat a deprecation as "still works, but plan to move." Nothing disappears from /v1 — deprecated
items keep working for the life of /v1; removals happen only at the /v2 boundary.