Retailer API Release Planning and Lifecycle

This topic describes the release planning and application lifecycle for the bol.com Retailer API. In order to provide our users with a stable platform we offer predictable releases, clear deprecation periods, and a clear and well-communicated roadmap.

Application Lifecycle

In the Retailer API we will support at most three versions in production at a time. We currently aim to release a major version of the Retailer API every 6 months. The example below shows how this will affect releases:

Date v1.x v2.x v3.x v4.x

01-01-2000

GA

ALPHA/BETA

N/A

N/A

01-07-2000

GA

GA

ALPHA/BETA

N/A

01-01-2001

DEPRECATED

GA

GA

ALPHA/BETA

01-07-2001

REMOVED

DEPRECATED

GA

GA

In effect, this means every version will live for at most 18 months before being permanently removed. Consumers of the Retailer API can skip one major version of the API before they have to upgrade. This gives consumers flexibility to decide when to migrate their applications, and a chance to plan for these investments accordingly.

To signal to consumers that a version has been deprecated we will provide deprecation headers to the versions marked as deprecated. We ask consumers to keep track of these deprecation headers whenever they may appear and to take action to migrate to a new version of the Retailer API when convenient, before removal occurs. We will not postpone our removal schedule.

Alpa/beta endpoints can be added at any time during or after the major release. Anything except a major GA release will not follow a strict 6-month release schedule.

Scheduled releases

At this time, the following major Retailer API releases have been planned:

  • 01-10-2020: Retailer API v4

  • 01-04-2021: Retailer API v5

  • 01-10-2021: Retailer API v6

Roadmap and release content will be communicated using the appropriate channels.

Versioning scheme

The Retailer API will follow a strict versioning scheme. We identify two types of releases - minor and major. The current version for the application will be explicitly communicated in the release notes. The structure of the version number is <major version>.<minor version>.

For users the major version is the most important version number to be aware of; when consuming endpoints they provide headers to tell the API which version they are consuming. In this header only the major version is provided; consumers will always get the response from the most recent minor version in production.

application/vnd.retailer.v4+json

Minor versions

Minor versions of the Retailer API will be rolled out any time it becomes convenient. Under normal circumstances these releases will not require any downtime. For minor versions the following rules apply:

  • Allowed: Adding new optional fields to a request body, provided this doesn’t change the endpoint behavior

  • Allowed: Adding new optional query parameters to the request, provided they don’t change endpoint behavior and have well-defined default values

  • Allowed: Adding new fields to a response

  • Allowed: Adding new supported media types for endpoints

  • Allowed: Adding new endpoints in the alpha or beta stage

  • Disallowed: Any changes beyond previously listed changes that can break client implementations. These should be planned in major releases.

Minor releases are guaranteed to be backwards compatible.

Major versions

Larger, breaking changes to the Retailer API will be rolled out following an explicit, pre-announced schedule. These releases will roll out a new major version next to the existing Retailer API versions currently in production, while possibly also deprecating old versions – which will still be available but scheduled for removal in the future. In major releases all changes are allowed, provided they are properly documented in a migration guide.

Major releases are not guaranteed to be backwards compatible.

Retailer API endpoint stages

In order to have maximum predictability and stability, and to allow users to adjust and conform to changes in the Retailer API, the Retailer API follows a strict versioning scheme.

The following stages are used in the Retailer API lifecycle. These stages can apply to individual endpoints but mostly apply to complete API versions:

Alpha stage

In the Alpha stage, endpoints are made available for trial use. They can be exposed publicly or via opt-in. In some cases these endpoints are restricted to users who explicitly signed up for the trial.

Alpha endpoints will announce their Alpha status by exposing an Alpha header. Alpha API endpoints…​

  • Will be provided as-is in an early access mode

  • Can be removed or change at any time in any way

  • Can be aggressively rate-limited

  • Will receive no or very limited technical support from Partner Service.

Whenever applicable for updated endpoints, previous versions will still be supported as a fallback.

Usage of endpoints in the Alpha stage is discouraged for production systems and intended for feature evaluation purposes only.

Beta stage

In the Beta stage, endpoints are available for open trials. They can be exposed publicly or via opt-in. In some cases these endpoints are restricted to users who explicitly sign up for the trial explicitly. Beta endpoints will announce their Beta status by exposing a Beta header. Beta API endpoints…​

  • Will be provided as-is in an early access mode

  • Are frozen for modifications. Only bug fixes and necessary modifications will be applied.

  • Will work with general availability rate limits

  • Will receive limited technical support from Partner Service.

Whenever applicable for updated endpoints, previous versions will still be supported as a fallback.

Usage of endpoints in Beta stage is discouraged for production systems and intended for feature evaluation purposes only. Beta endpoints will be released in the future but could still contain bugs, performance issues and other defects, which are being addressed during the Beta stage.

GA (General Availability) stage

In the GA stage, endpoints are available and recommended for production use. They are made openly available to all Retailer API users after successfully completing Alpha and/or Beta stage. GA API endpoints…​

  • Will be final and will not be subject to breaking changes

  • Will work with general availability rate limits

  • Will receive full technical support from Partner Service.

Deprecation stage

New versions of the API will be released at a predetermined and announced fixed interval. Whenever a new version of a particular endpoint is released the endpoint it supersedes is marked Deprecated and will be scheduled for removal in the next major release of the Retailer API. Deprecated API endpoints…​

  • Will be final and will not be subject to breaking changes

  • Will work with general availability rate limits

  • Will receive full technical support from Partner Service

  • Will be removed in the next release for the Retailer API.

We recommend that you migrate from deprecated endpoints to the latest GA release as soon as possible at the latest, before a newer release of the Retailer API becomes available and removes support for these endpoints.

Support

During GA and Deprecation stages, the Retailer API will be fully supported and all endpoints will remain active until their final removal.

We strongly recommend that you migrate to newer versions of the Retailer API before the removal window is closed, as new features and fixes in the Retailer API will provide a better user experience and will only be applied to GA endpoints, whereas deprecated endpoints will only be subjected to maintenance in case of critical issues.

Alpha/beta endpoints are being actively developed which means there are no stability guarantees, so it is strongly discouraged to uses these endpoints other than for testing purposes.