Versioning and deprecation

The daisyBill API is versioned in the URL. Every endpoint is under /api/v1/.

What v1 means

v1 is the major version of the API. Within v1, we do not make breaking changes without notice. A change that would break existing integrations either goes into a new major version (v2) or follows the deprecation process below.

Breaking changes

These changes can break an integration. We announce them in advance:

  • Removing an endpoint
  • Removing or renaming a request or response field
  • Changing the type or format of a field
  • Making an optional request parameter required
  • Returning a different status code for a request that used to succeed

Changes that are not breaking

We make these changes at any time, without advance notice:

  • Adding an endpoint
  • Adding an optional request parameter
  • Adding a field to a response
  • Adding a value to an enum, for example a new bill status or event type
  • Fixing a bug so that the API behaves as these docs describe, for example returning 400 instead of 500 for an invalid request

Build your integration to ignore response fields and enum values it does not recognize.

Deprecation policy

Before a breaking change, we give at least 90 days' notice:

  1. We email the users who have an active API token.
  2. We add an entry to the changelog with the date the change takes effect.
  3. Until that date, the current behavior keeps working.

Changelog

The changelog lists changes to the API by date, including changes that are not breaking.