API versions

The Carepatron Public API is versioned by date. A version is named for the day it was released, and a request receives the request and response shapes of the version it pins.

Pinning a version

Send one of the versions listed below in the cp-api-version header on every request. A request without the header is refused with 400 missing_api_version_header, and one naming a version this API does not serve with 400 unknown_api_version.

Breaking and additive changes

A breaking change is released only in a new version. These changes are breaking:

• removing an operation;
• removing or renaming a parameter or a response field;
• adding a required parameter, or making an optional one required;
• changing a type;
• removing an enum value;
• adding a validation rule;
• changing authentication or authorization;
• changing what an operation does in a way its schema cannot show, such as taking in records it used to leave out.

Additive changes reach every supported version at once, with no new version: a new operation, an optional parameter or request header, a response field, or a response header. The contract's object schemas are closed (additionalProperties: false), so validate a response against the current contract of the version you pin, or ignore members you do not recognise. Each version's contract below is kept current with every additive change.

Support policy

A version is supported for at least 24 months after a newer version is released. Releasing a version deprecates the one it replaces and schedules that version's end of support.

An operation's response to a request pinned to a deprecated version carries the headers below, including a response replayed for a repeated Idempotency-Key. A response that does not come from an operation, such as an authentication failure, a rate limit or a server error, does not carry them.

• Deprecation - when the version was deprecated, as @ followed by Unix seconds (RFC 9745);
• Sunset - when it stops being served, as an HTTP date (RFC 8594);
• Link - the version's page as rel="deprecation", and this page as rel="sunset".

After its end of support, a request pinned to the version is refused with 400 unknown_api_version.

Moving to a newer version

1. Read the newer version's page for its breaking changes and how to migrate from each.
2. Try it: pin the newer version on individual requests while the rest of your integration stays where it is.
3. Change the cp-api-version header everywhere.

Supported versions