Stability and versioning
What integrations can rely on, how the API changes and where to download the contract.
Two version numbers
| Version | Where | Changes when |
|---|---|---|
| Path version | /api/v1 in every URL | An incompatible change to published operations is made. |
| Contract version | info.version in the contract, currently 0.10.0 | The contract changes in any way. |
The changelog lists each contract version with its changes.
What you can rely on
The published contract (ADR-020) contains exactly the operations integrations may use: the operations that
accept an API key and the public passport reads (tag public). Everything in it is the API this
documentation describes and the API reference lists.
The BatteryPass portal uses further, internal operations: sign-in, members, API key management, review, publishing, imports. They are not in the published contract, need a portal session and may change in any release without notice. Do not build on them.
Compatible changes
These changes can come in any release without a new path version:
- new operations;
- new optional query parameters and new optional properties in request bodies;
- new properties in responses;
- new enum values, for example a new passport status or lifecycle event type;
- new problem codes and field error codes;
- a new version of the field registry with new fields, labels or requirements (read it with
getRegistryInfo).
Write your client so that these do not break it:
- ignore response properties you do not know;
- handle unknown enum values with a sensible default instead of failing;
- treat an unknown problem
codeby its HTTP status; - do not validate responses strictly against an older copy of the contract.
Incompatible changes
Removing or renaming an operation, parameter or property, changing a type or meaning, or making optional input required is incompatible. Such changes to published operations come only with a new path version and are announced in the changelog.
Download the contract
The contract is an OpenAPI 3.0 document, as JSON and YAML, without authentication:
| Address | Content |
|---|---|
$BATTERYPASS_URL/api/v1/openapi.json, $BATTERYPASS_URL/api/v1/openapi.yaml | The contract of the BatteryPass deployment your organisation uses |
/docs/openapi.json, /docs/openapi.yaml | The contract this documentation describes |
For your integration, the contract of your deployment is authoritative: it matches the version that answers your requests and can be older or newer than the one on this site. Check its version before you generate a client:
curl -sS "$BATTERYPASS_URL/api/v1/openapi.json" | jq -r '.info.version'Generate typed clients from the contract and keep the info.version you generated from. Comparing it with
the deployed version in your monitoring tells you when to read the changelog.