Skip to main content

API versioning strategy

API versioning is the practice of managing changes to an API and ensuring these changes are made without disrupting clients. A good API versioning strategy clearly communicates the changes made and allows API consumers to upgrade to the latest version at their own pace.

Voyado is introducing a new API versioning model for Engage, to enable their developer teams to release new and changed functionality that extends the API in a controlled way.

The new model gives Voyado's client´s developers (both partner and in-house) improved and updated documentation, including well-defined release notes for all changes to the API.

The Engage API today

Today the Engage API is on version 2 and looks like this:

  • One common API versioning scheme is used for all endpoints

  • V1 and V2 of the API can be used independently

  • Minor changes done rarely, no new version release since 2017

  • V1 is considered deprecated but is still in use

How do we define changes?

The definition of what is a breaking and a non-breaking change is vital in understanding the Engage API versioning strategy.

The following are examples of non-breaking changes:

  • Adding an optional field to a request message. Existing client code will not be forced to use the new field.

  • Adding a required field with a default value to a request message. The server will add the default value if the client does not send it.

  • Adding a field to a response message. Existing client code should ignore any such new fields. Clients should not implement a mapping that raises an error for new fields.

These are examples of breaking changes:

  • Renaming fields or resource paths in a way that requires client code to change.

  • Renaming or removing fields in a request or response message.

  • Removing API operations used by existing clients of the API.

  • Changing fields from single value to multiple value (like from a single email per member to a list of email addresses).

  • Changing the HTTP method or the response codes returned by an API operation.

The API versioning vision

The Engage API should be reliable, scalable and easy to use, providing clients with real-time access to their core CXM environment. There are four key goals:

1) Adapt to business requirements

Voyado's developers must be able to release new or changed endpoints to production whenever they are ready. This will work like this:

  1. Non-breaking changes will be developed and released continuously to production by Voyado's teams following the normal release process.

  2. Breaking changes (that trigger a new version) will also be released continuously but will be hidden behind a feature toggle.

  3. Breaking changes should be collected into official releases, ensuring consistent communication both externally and internally.

  4. First-mover clients may be selected to use pre-released API functionality before official releases, although with limited support.

2) Backward compatibility

To ensure backward compatibility:

  1. Voyado will not force clients to upgrade their API version, and will avoid impacting working integrations by keeping multiple supported versions in parallel.

  2. Voyado will warn well in advance before moving a version to an unsupported end-of-life state, giving clients time to upgrade.

  3. Voyado will deprecate versions in a controlled manner, and have a dialogue with clients still using unsupported version to help them upgrade.

3) Keep API documentation up-to-date

Voyado will ensure clear communication and up-to-date documentation.

  • New versions with breaking changes will require all related API documentation to be updated and clear release notes to be communicated both externally and internally.

  • Minor non-breaking releases will also require changes to API documentation as well as clear release notes.

4) Be transparent and consistent

Voyado will be as transparent and consistent as possible with API roadmaps and release notes.

  • Voyado will publish and communicate the new API versioning model externally to partners and clients.

  • Voyado will communicate the new API version strategy and versioning model to all Voyado departments.

  • Voyado will train their dev teams to use the new API versioning model.

Important

The goal is for new functionality to only be released in the current API version, to minimize maintenance but also to give our clients an incentive to upgrade to the latest version, increasing the number and quality of features they have available to them. However, an older API version could sometimes be updated to use newly released code if that simplifies overall code maintenance.

API release status

These are the lifecycle phases for an API version:

api-versioning-status.png

Limited: Only accessible by selected clients (used in development).

Current: The latest release. New releases will be introduced regularly, but there is no fixed release schedule.

Active LTS: Long term support. There is no set time limit, it depends on the support cost and how much that version might limit development.

Deprecated: A version not supported but still active. Clients are notified at least 6 months in advance if a deprecated version is to be moved to end-of-life.

End-of-life: This version is not supported. It may be deleted or redirected to a newer version. It will be removed when not used by any client.

Strategy in a nutshell

These are the important points of the Engage API versioning strategy:

  1. Versioning will be separated on an application level (Engage, Elevate Storefront, Elevate Admin). Note that the API versioning in Engage is not connected to the API versioning in Elevate.

  2. A single version will be used for all Engage API endpoints.

  3. A new API version will be released when breaking changes are introduced.

  4. An old API version will be supported for at least 18 months.

  5. Non-breaking changes will be automatically applied to the latest version.

In this section: