Breaking Changes

We aim to limit any breaking changes. Where necessary, major changes may be rolled out over versioned endpoints and upgrading would be required to support new features.

Truly breaking changes, that would require changes to your code, are considered a last resort. They will be communicated in advance and we’ll coordinate and support your updates.

A change is breaking when an existing integration stops working while still sending the same requests.

Some changes we treat as non-breaking can still be breaking changes to generated API types. We’ll roll out major versions of our SDKs where possible. Existing integrations keep working at runtime.

Request Shape

Breaking

Adding a new, required, field
Modifying the data type of an existing field
Removing support for enum values that were previously accepted

Non-breaking

Adding a new, optional field
Removing a field that was previously optional
Making a required field optional or nullable. Existing requests keep working. You only get the new behavior by changing what you send.

Response Shape

Breaking

Removing a field
Changing the data type of an existing field
Making a field nullable, when an existing response can return null without a change to the request

Non-breaking

Adding a new field
Making a field nullable, while clients that still send the original request keep the original response contract

Introducing optional

Patient create email:

// existing contract
request: { email: string }
response: { email: string }
// introducing optional
request: { email?: string | null }
response: { email: string | null }

The existing contract still holds. Clients that still send email: string receive email: string on every response.

Enums / Union Types

Enums and union types determine acceptable values for a single field. The breaking/non-breaking definitions here are generally true.

The only thing we consider a breaking change, is the removal of an enum value or union type that was previously accepted, inside a request.

Additional enum values or types, in either request or response, are considered non-breaking.

We expect client integrations to be able to handle “unknown” enum values and types gracefully.

Behavior Changes

Breaking behavior changes, tied to API changes, are breaking API changes

In addition to the conventions here, generalized breaking changes to concepts and behavior may render an API change as breaking.

For example, the addition of a status value in a Service lifecycle would be considered critical enough to be breaking.

However, the additional of a triage TaskType would not be considered breaking - it should be treated as unknown.