API compatibility policy
This page describes which changes to the Provet REST API we treat as breaking, which changes we make as part of normal development, and what your integration needs to do to keep working as the API evolves.
What we guarantee
Within the API as it stands today:
We will not remove or rename an endpoint you are using.
We will not remove or rename a field in a response.
We will not change the type of a field.
We will not add a new required parameter to an existing request.
We will not make an optional parameter required.
We will not remove a value from a set of values a field can return.
We will not add a new validation rule to an existing parameter.
If we need to make one of these changes, it is a breaking change covered by the process below.
What we may change at any time
These changes are additive. They do not break a well-built integration, and we make them as part of normal development without a version change or advance notice.
Adding a new endpoint.
Adding a new optional parameter to an existing request.
Adding a new field to a response.
Adding a new value to a field that returns a fixed set of values, such as a status.
Adding a new event or notification type.
Changing the order in which fields appear in a response.
Changing the wording of an error message, or adding a new error code.
Changing the length or format of an identifier, or of any other opaque string.
What your integration needs to do
An additive change cannot break an integration that does these things.
Ignore fields you do not recognise. Read the fields you need and pass over the rest. Do not fail validation on a response because it contains something new.
Handle values you have not seen before. Several fields, including health plan statuses, return a fixed set of codes, and we add to those sets over time. Your code needs a defined path for a code it does not know.
Match the values you need rather than listing them all. Handle the values your integration acts on, and route the rest to a single default path. An exhaustive mapping needs updating every time we add a value.
Treat an unrecognised code as unknown rather than as a default outcome. Some fields return integers rather than strings, so an unfamiliar code carries no indication of its meaning. Where a code is unrecognised, the safe reading is that the state of the record is not yet established, rather than that it is inactive or complete.
Do not depend on field order, error message wording, or the shape of an identifier. Store identifiers as opaque strings and match on error codes rather than on message text.
Version your own integration against our specification, not against a snapshot of a response. A recorded response body is a sample, not a schema. Build against the OpenAPI specification we publish.
When we correct defects
Sometimes a field returns the wrong value, or returns a value when it should not. When we correct that, the values you receive change, even though nothing about the shape of the API has changed.
A defect correction is not a breaking change. We make these corrections without a version change and announce them in the release notes.
We cannot tell from our side whether your integration depends on the incorrect behaviour, because the API cannot distinguish a client that reads a status from one that has a fixed list of statuses.
If a correction does affect you, tell us and we will help you work through it. We will always correct a defect, and we will give you the support you need to adapt to it.
Staying informed
Read the changelog for every additive change, breaking change and defect correction that affects the API. It is also available as an RSS feed.
Use the OpenAPI specification as the current contract, and generate your client from it.
If you are building a large integration, tell your account contact. Knowing which fields you depend on lets us give you advance notice of the changes that affect you.