Breaking changes on the HubSpot platform

When developing an integration on the HubSpot platform, you'll need to be aware of the types of changes that HubSpot might make to its platform or data within. Below, learn about what HubSpot considers a breaking or non-breaking change, and use these lists to inform decisions you'll 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.

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. 

Below, learn about what changes are breaking for incoming and outgoing RESTful APIs (e.g., contacts API and 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)

Non-breaking changes

• Changing the error message
• Adding a new option to a response (e.g., adding a new possible return value to a string field)
• 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.

Below, learn about what changes are considered breaking for HubL (e.g., the hubdb_table_rows function or 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

Non-breaking changes

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

Below, learn about what changes are considered breaking for embedded content (e.g., forms and CTAs).

Breaking changes

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

Non-breaking changes

• Add an optional setting for customizing the behavior of the embed

Below, learn about what changes are considered breaking for JavaScript SDK (e.g., the 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

Non-breaking changes

• Adding a new function

Occasionally, there will be changes to the schema that describes the data share. Any change that makes querying a share fail due to changing an existing schema object is considered a breaking change.

For example, renaming a table is a breaking change for the Snowflake Data Share integration because queries referencing the former name of the table will fail after the rename. In this case, HubSpot will add a new table with the same data to the share so that you can begin using the new name. The old table will continue to exist until the end of the 90 day notice period.

Below, learn about what changes are considered breaking for the Snowflake Data Share.

Breaking changes 

• Removing or renaming the database schema
• Removing or renaming a table or view
• Removing or renaming a column
• Changing a column's datatype
• Column nullability

Non-breaking changes

If a change is listed as a non-breaking change, it will be added to the schema with no notice given. For example, adding a new column to the schema.

This means that queries accessing shares should be as specific as possible when referencing schema objects. For example, you should always qualify tables by specifying the database schema they belong to. It also means that you shouldn’t use the SELECT *  clause in your queries, because that might break when a new column is added.

The following are examples of non-breaking changes:

• Adding to the database schema
• Adding a table or view
• Adding a column
• Changes to objects and their properties (e.g., the data within the objects and object_properties tables and views)