What is a breaking change?
Understand how Gusto versions its API and what changes may require updates to your integration
Gusto's API versioning follows Semantic Versioning principles. We distinguish between breaking changes—those that are likely to require updates to your integration—and backward-compatible changes that your integration should tolerate without modification.
Our goal is to minimize breaking changes and give you advance notice when they do occur. When we release a new API version, we'll document exactly what changed and what action (if any) is required on your end.
For a detailed list of all breaking changes by version, see the version upgrade guide.
Changes that are considered backward compatible, such as additions of response fields, could potentially cause issues with your integration.
Ensure that your client can handle all backward-compatible changes.
Backward-incompatible changes
The following types of changes are considered backward incompatible:
Structural changes
- Removing or renaming endpoints, fields, or parameters
- Changing data types of existing fields
- Adding new required fields to requests
- Changing authentication methods or required scopes
Behavioral changes
- Changing default values (sort order, page size, or boolean defaults)
- Changing error codes or HTTP status codes
- Tightening validation rules (new regex patterns, stricter formats, or new uniqueness constraints)
- Changing serialization formats (date formats, null handling, or enum value representations)
- Changing pagination behavior (default page size, ordering, or cursor format)
- Bug fixes where the corrected behavior differs from the previous behavior, even if the previous behavior was incorrect
Backward-compatible changes
We consider the following to be backward-compatible, non-breaking changes.
- Adding new API endpoints
- Adding new optional parameters to existing endpoints
- Adding new fields to response bodies
- Adding new values to existing enum fields
- Changing the order of properties in existing API responses
- Loosening validation rules (longer max length or more allowed values)
- Making previously required fields optional
- Bug fixes that don't change observable behavior
Handle backward-compatible changes defensively
Some backward-compatible changes can still cause issues depending on how your integration is built.
You should build your integration to tolerate additive changes such as the following:
| Type of additive change | Our recommendation |
|---|---|
| New response fields | If your integration uses strict schema validation that rejects unknown properties, new fields in a response body could cause failures. We recommend configuring your JSON parsing to ignore unknown fields. |
| New enum values | If your code uses exhaustive switch/case statements on enum fields, a new value will fall through. We recommend always including a default or fallback case when handling enum values from our API. |