Contract Guidelines: Breaking Changes

This document outlines what constitutes a breaking change in our API and how we handle modifications to ensure compatibility with existing clients. We follow industry best practices to maintain stability while evolving our API.

Non-Breaking Changes

Adding a New Field

The addition of a new field is not considered a breaking change, provided the following conditions are met:

• The new field is optional and does not alter the API's existing behavior.
• Existing clients can continue using the API without interacting with or being affected by the new field.
• Clients who do not expect the new field will be able to ignore it safely without any changes on their side.

Impact on Clients with Strict Validation

Strict Validation: If a client enforces strict validation (for example, rejecting responses with unexpected fields), the addition of a new field might lead to issues. In such cases, although we consider the change to be backward-compatible, these clients may experience validation failures. We strongly recommend configuring clients to allow for flexible response structures.

Documentation Updates

All new fields will be documented, with an emphasis on their optional nature. Clients are encouraged to review the updated API documentation periodically to stay informed about new capabilities.

Backward Compatibility

We strive to maintain backward compatibility by ensuring that any changes (such as the addition of fields) do not affect clients who are not prepared to handle the new fields. This allows clients to upgrade at their own pace.

Breaking Changes

The following types of changes will be considered breaking changes and will require careful consideration and versioning:

• Removing an Existing Field: Deleting a field that clients currently rely on will break their integrations.
• Changing the Data Type of a Field: Altering the expected data type of a field (e.g., changing an integer to a string) will break clients that expect the original data type.
• Modifying Mandatory Fields: Changing an optional field to a mandatory one, or changing the expected behavior of a mandatory field.
• Renaming Fields: Changing the name of a field that clients rely on will result in breaking functionality for clients that expect the original field name.
• Altering Response Structure: Significant changes to the overall structure of the response, including nesting fields or reorganizing data, can disrupt existing client implementations.
• Modifying Endpoint Behavior: Changing the logic or expected behavior of an endpoint (e.g., changing the HTTP status codes or error responses) in a way that affects existing clients.
• Adding a New Enum Value: Introducing a new value to an existing enum may break clients that do not handle unexpected values or enforce strict validation of enum values.

Versioning Policy

For any breaking changes, we will follow a versioning policy to ensure that existing clients are not impacted:

• Version Bumping: A new major version of the API will be released to accommodate any breaking changes. Clients can continue to use the previous version of the API until they are ready to upgrade.