The Middesk API has a major-release versioning strategy. But, to-date, all API changes have been bundled in to version 1 (v1); we have yet to release a major version 2 (v2). Since we're not relying on sub-versioning as we introduce incremental changes, we wanted to cover how we think about breaking and non-breaking changes, and a couple of sub-categories within each.

Breaking Changes

Middesk considers a breaking change as one made to a software system that is not backwards compatible with the previous version, and can cause existing software integrations to fail or behave unexpectedly. This means that any software that relies on the previous version will need to be updated or modified in order to function correctly with the new version. We rarely release breaking changes as there are almost always change strategies that preserve backwards compatibility. But, if we have no choice, we will give each customer advance notice and the option to opt-out of the change.

Examples of Breaking Changes

The following modifications are considered backwards incompatible:

Removing, renaming, or changing the value of existing properties of an existing API endpoint, such as removing a field in our JSON response or removing or modifying an expected value.
Changing the response type of an existing API field
Removing or deprecating an existing API endpoint.
Changing the authentication method or security protocols used by the API.
Decreasing a rate limit.
Removing existing webhook events.

Non-Breaking Changes

Middesk considers a non-breaking change as one that is backwards compatible with the existing API. Backwards-compatible changes fall mostly into the additive category. We've found that generally, in software engineering, additive changes don't lead to breaking changes (it's better to add than to take away). However, we acknowledge that they can lead to behavioral changes that potentially may be unwanted or unknown by customers.

Examples of Non-Breaking Changes

The following changes are considered backwards compatible:

Adding new API resources (endpoints).
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.
Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
Adding new webhook events.
Changing the meaning of an existing API field.

While the definition and examples above do generally constitute backwards-compatibility, we acknowledge that even these changes can be disruptive to your business logic. Here's how we think about non-disruptive and disruptive changes:

Non-disruptive

Many changes we make to the API are non-disruptive and can be added without worrying about disrupting your flows. We aim to keep API changes in this category when possible.

Examples

Adding new resources and API endpoints that aren’t yet used by any customers. This approach was followed when we added policies.
Adding a new type of task.
Adding new fields to the Businesses API. For example, the new sub_status field in the Registrations response.
Adding additional optional filters to GET /v1/businesses

Disruptive

Sometimes our customers have specific requirements or preferences for how an API should work or behave. These preferences may conflict with proposed changes to the API, even if those changes are backward compatible. In some cases, the customer may simply prefer to maintain the current API behavior or interface, even if it means missing out on new features or improvements. And that's ok.

Examples

Verifying addresses with a new data secondary data source such as Google Places or Websites, in addition to government sources.
Adding a new webhook event type, and automatically subscribing customers.
Changing sources for our a watchlist database.
Adding a new value for “success”, “warning”, or “failure” on an existing insight or task.

In these cases, we use a feature-flagging system to opt customers in to these disruptive changes after proactively reaching out about them well in advance.