Breaking Changes Policy

At Billwerk+ Premium & Enterprise, we are dedicated to the continuous improvement of our API. We recognize that changes are integral to progress and are committed to advancing our services. However, we understand that changes can affect our users' operations, and we manage these transitions.

What Constitutes a Breaking Change?

The following are considered breaking changes:

• Removing Properties: Eliminating fields or properties from existing models.
• Renaming Properties: Changes to the names of properties, except case sensitivity adjustments.

We will inform users about breaking changes directly and provide a transition period to adapt to new changes.

For detailed advice on integration practices and handling changes, contact us at [email protected].

Please note that not every change warrants direct communication. Some changes, by our definition, are non-breaking and will be handled as such:

• New Enum Values: Adding new values to existing enums is non-breaking.
• Additional Properties: Adding fields to existing models does not require changes to consumer code.
• New Endpoints: Introducing additional API functionality is considered an additive change.
• Case Sensitivity: Our API accepts all case variants of property names, and changes to cases in documentation do not affect integration.
• Renaming DTO

We recommend designing your integration to be resilient to changes. Expect and ignore new, unexpected types, enum values, or fields to ensure seamless continuity.

Example: Modifying DTOs Without Breaking

To clarify how non-breaking changes might look in practice, consider the following evolution of an API:

Initial Version

class FooDTO
{
    string Name;
    DateTime CreatedAt;
}

The first version of the API supports a GET /foo that returns a FooDTO with Name and CreatedAt fields.

Subsequent Version

In a later version, if we add a PUT /foo endpoint, we can reorganize the FooDTO without causing a breaking change:

class FooDTO // Used by `PUT /foo`
{
    string Name;
}

class FooReadDTO : FooDTO // Returned from `GET /foo`
{
    DateTime CreatedAt;
}

By splitting FooDTO into FooDTO for the PUT request and FooReadDTO for the GET response, we ensure backward compatibility while supporting clear and focused data structures for each operation.