Versioning

📌

Akoya API versions are set in the path

Incremental changes in a version will be listed in release notes and maintain backward compatibility. The current Akoya version is Akoya API v2.

This guide outlines the Akoya API versioning approach and our goals in defining and supporting our users with any breaking changes created with API updates. We aim to limit breaking changes as much as possible to new API versions (a.k.a. major versions). This is achieved by only releasing non-breaking changes (a.k.a. backward compatible) to current API versions.

API major version timeline

Major releases will be communicated in advance to give our 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 be 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 will 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

📘

Implementation note

A data recipient implementing Akoya APIs should expect to see non-breaking changes rolled out regularly through minor version updates. Please implement the Akoya APIs in a way that allow for these changes.