API Versioning

API major version timeline

Akoya communicates major releases in advance to give users time to understand upcoming changes. With a new major version release, the previous version will be automatically deprecated.

Six months after deprecation, the previous version will sunset. Once a version is sunset, it will no longer be available or supported.

When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. New implementations of Akoya APIs should implement the latest (non-deprecated) major version.

Akoya APIs and breaking changes

We increment API major version numbers for any non-backward compatible changes to an API. The following examples are principles to define breaking changes vs. non-breaking changes.

Examples of breaking (non-backward compatible) changes:

• Changes to the URL or fundamental request/response associated with an endpoint

• Removal, rename, or change to the type of a declared property

• Removal, rename, or change to a data field

• Removal or rename of APIs or API parameters

• Addition of a required request header

• Changes to an existing query parameter or addition of new mandatory request parameters

Examples of non-breaking (backward compatible) changes:

• Addition of net-new data fields

• Addition of properties that are nullable or have a default value

• Addition of a member to an enumeration

• Removal, rename, or change to the type of an open extension

• Removal, rename, or change to the type of an annotation

• Introduction of paging to existing collections

• Addition or changes to error codes

• Changes to the order of properties

• Changes to the length or format of opaque strings, such as resource IDs