Versioning

Version numbers

Major version

The Acquisio APIs are versioned with a single number for major versions. The major version is included in the url of the API and will be incremented when incompatible API changes are done.

Semantic version

Each Acquisio API also has a semantic version.

  • A major version can contain breaking changes that render the API incompatible with previous version.
  • A minor version makes changes to the API which will not deviate from the function of the previous minor version.
  • A patch version includes backward-compatible bug fixes.

Release notes

  • Each major version of an API has its own release notes.
  • Minor versions are documented in the release notes of each API.
  • Patch versions might be documented or not, depending on the impact of the bugs on the users of the API.

Breaking changes

The following changes are considered breaking changes:

  • Adding a new mandatory field to a resource for which no default value can be set
  • Changing the type of a field
  • Renaming a field
  • Removing a field
  • Removing an endpoint
  • Changing the url of an endpoint
  • Renaming an enum constant

The following changes aren’t considered breaking changes:

  • Adding an endpoint to an API
  • Adding a new field to a resource (if the field is optional or has a default value)
  • Adding a new optional query parameter with a default value (?parameter=value)
  • Adding a new error code (see Acquisio APIs Error Codes)