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.
In general, we consider any modification that would render a previous request/response invalid when validated against a parser, to be breaking.
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
Response Shape
Breaking
- Marking a field as optional/nullable, when it was previously required
- Changing the data type of an existing field
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
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.