API Change management

Breaking Changes

A breaking change to an API can cause errors or disrupt applications that use it by modifying how the API works.

Here's what constitutes a breaking change:

• Validation changes: Adding new validation rules or modifying existing ones for parameters.
• Endpoint functionality: Altering the intended purpose or behavior of an endpoint.
• Required parameters/headers: Introducing mandatory parameters or headers to existing endpoints.
• Error & Status Codes: Modifying the error codes or status codes returned by endpoints.

Non-breaking changes, on the other hand, add new functionalities without affecting existing integrations. These include:

• New Endpoints: Adding entirely new functionalities through new endpoints.
• Optional Parameters: Introducing optional parameters that clients can choose to use.
• Additional Response Fields: Expanding the data returned by existing endpoints with new fields.

Versioning and Communication

While we strive to minimize breaking changes, they are sometimes necessary for improvements. We use a versioning system to manage them. Breaking changes are introduced through major version increments in the API base URL (currently https://api.tallbob.com/v2).

Important: When a new major version is released, we will maintain the previous version for at least 12 months. We will also proactively communicate all breaking changes to our Account Owners and Vendor Integrators.