What is a breaking change

It can be really frustrating when you have a user telling you your app broke but you haven’t made any changes to it. Sometimes, this is because a system you are integrating changed something and didn’t tell you. Below, we’ve defined what we consider a breaking change (and a couple of things we don’t think should break your app).

How to use this

You can use the list of breaking and non-breaking changes to guide some of the decisions you'll need to make when working with HubSpot's APIs. If a change is listed as a breaking change, we aim to provide you with 90 days notice if we do decide to make that change. Note that this notice period applies to developer products released to general availability. For beta and developer preview products, we’ll continue to update those regularly as we learn more about them. Note also that in certain situations, such as those related to security or privacy, we may shorten that 90 day timeframe.

As an example of correctly handling non-breaking changes, you can safely write (in pseudo code here) if err.code === 500 then retry but you should not write if err.message === "Uh oh, something went wrong" then retry. By asking yourself the question "if HubSpot makes a change listed as non-breaking, will this negatively impact the user experience?", you can write code that will be easier to maintain and create a more reliable app. 

RESTful APIs (incoming and outgoing) - ex. Contacts API, webhooks 

Breaking Changes 

  • Removing an endpoint
  • Removing a field from the response (a “field” in this case is a JSON key/value pair)
  • Removing an option from a field in the request - If a request field could previously accept two String values, and we remove the ability to accept one of those, that would be a breaking change
  • Adding a new required field, header, or parameter in the request
  • Renaming a field
  • Changing the data type of a field
  • Changing field lengths past industry standard data limits (int, long, etc.)
  • Changing error response code or category
  • Changing auth types
  • Restricting scope
  • Reduce API limits
  • Making validation more stringent
  • Changing the default sort order
  • Significantly increase the size of a response (10x)


Not a breaking change:

  • Changing the error message
  • Adding a new option to a response - If we add a new possible return value to a string field, for example, that would not be a breaking change
  • Adding a new optional input parameter
  • Property labels changing - Labels can be changed by HubSpot, application providers, and even customers. Integrations should not rely on property labels for their functionality.

 

HubL - ex. Hubdb_table_rows function, escape filter

Breaking changes

  • Removing a filter, function, variable or tag
  • Adding a new required argument
  • Changing the order of an argument
  • Change the data type of a field in a module/theme field JSON
  • Reduce the number of times a function can be invoked on a page


Not a breaking change:

  • Adding a new optional argument
  • Adding a new function, filter, variable or tag

 

Embedded content - ex. Forms, CTAs

Breaking changes

  • Adding or removing class names
  • Changing the timing/execution of custom form events (e.g. onFormSubmit)
  • Changing the timing/structure of global form events

 

Not a breaking change:

  • Add an optional setting for customizing the behavior of the 

 

Javascript SDK - ex. Calling SDK

Breaking changes 

  • Removing an operation
  • Requiring a new argument to a function or field in an object that is passed to the function
  • Changing order of required parameters
  • Changing data type returned

Not a breaking change:

  • Adding a new function