Retailer API Release Planning and Lifecycle

This document 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. This document describes the relevant elements for this process.

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. This will have the following effect (using fictional dates):

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 the consumers flexibility to decide when to migrate their applications, and a change 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 as they may appear and to take action to migrate to a new version of the retailer API whenever convenient, before removal occurs.We will not postpone removal.

Please note that ALPHA/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 to 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 listed below:

<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 at any time when it’s 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 behaviour;

  • Allowed: Adding new optional query parameters to the request, provided they don’t change endpoint behaviour 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 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, stability and to allow users to adjust and conform to changes in the retailer API, the retailer API follows a strict versioning scheme.

We identify the following stages in the retailer API lifecycle (these stages can apply to individual endpoints but mostly apply to complete API versions):

  • ALPHA stage

  • BETA stage

  • GA stage

  • DEPRECATION stage

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 for users who sign up for the trial explicitly). 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;

  • ALPHA API endpoints can be removed or change at any time in any way;

  • ALPHA API endpoints can be aggressively rate-limited;

  • ALPHA API endpoints will receive no or very limited technical support from partnerservice;

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

Please note that usage of endpoints in 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 for users who sign up for the trial explicitly).BETA endpoints will announce their BETA status by exposing an BETA header.

  • BETA API endpoints will be provided as-is in an early access mode;

  • BETA API endpoints are frozen for modifications. Only bug-fixes and necessary modifications will be applied;

  • BETA API endpoints will work with general availability rate-limits;

  • BETA API endpoints will receive limited technical support from partnerservice;

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

Please note that 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;

  • GA API endpoints will work with general availability rate-limits;

  • GA API endpoints will receive full technical support from partnerservice.

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;

  • DEPRECATED API endpoints will work with general availability rate-limits;

  • DEPRECATED API endpoints will receive full technical support from partnerservice;

  • DEPRECATED API endpoints will be removed in the next release for the retailer API.

It is recommended to 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. It is strongly recommended to migrate to newer versions of the retailer API before the removal window is close, 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.