Developer Blog Series: What Is A Breaking Change?

A comment on a recent Community blog post raised a question about whether a planned change for the constituent API was a breaking change. This question prompted us to review our definition of breaking changes and document how we handle those changes. This blog post defines breaking changes for the SKY API, describes how we announce breaking changes and how often they occur, and provides some examples. We also added this information to the Basics section of the SKY API website.

We define a breaking change as any change to an API that could potentially cause failures in the applications that consume that API. If a change could cause API calls to fail or cause API calls to return different results than before the change, then we consider it a breaking change. Some examples of breaking changes include:

 

• Changes to entities. For example, if we change a property’s data type, then that property no longer accepts the previous data type and API calls with the previous data type may fail. Likewise, if we change a property’s name, then API calls will no longer recognize the previous property name.

  Old	Breaking return values
  {   "property": "value" }	{     "property": {       "value": true   } }

• Changes to response data types or status codes. For example, if we change the status code to return in a specific scenario, then API calls may no longer return the status code that a consumer expects when trying to catch a specific error.

  Old	Breaking return values
  POST /values returns 400 for missing property	POST /values returns 409 for missing property

• Changes to result sets for collection endpoints. For example, if we remove inactive entities from a default result set, then API calls to the collection endpoint will no longer return the same data as before the change.

  Old	Breaking return values
  GET /values returns all values	GET /values returns a limited subset of values removing "inactive" values

We strive to avoid breaking changes if at all possible, so breaking changes are few and far between. However, they are sometimes necessary. For example, if we determine that existing entities are not as helpful or intuitive as they should be and that developers aren’t using them as a result, then we may update the entities to address the problem and improve their usefulness and adoption. Likewise, critical issues or changes to underlying product services or data services sometimes lead to breaking changes, although we will try to mitigate as much as possible.

We only make breaking changes when we determine that they are critical, and we weigh the disruption that breaking changes will cause. Before making a breaking change, we check the usage of affected endpoints and entities and avoid changes to high traffic endpoints and entities if at all possible. The threshold to justify breaking changes to commonly used endpoints or entities is much higher than the threshold for less commonly used endpoints or entities, although any potentially affected endpoint usage is not taken lightly. The overall developer experience is always at the heart of every decision we make, including breaking changes. We value the trust we have built and want to continue to be transparent and reliable so that SKY API developers can continue to code with confidence.

To support this trust and transparency when we determine that a breaking change is worth the possible disruption, we announce the breaking change in the changelog for the affected API on the SKY API website and in the Community blog at least one week before we deploy the change. We provide this delay between the announcement and the actual change to give consumers of the API time to assess the impact of the change, to raise any questions, and to plan accordingly. Then when we deploy the change, we announce the breaking change again in the changelog and the Community blog.