API Release Life Cycle

The fulfillmenttools API is not strictly versioned. We don't use version numbers (see API Versioning) in the API and the API changes over time when we add new functionality. Each endpoint has a life cycle from alpha, beta, general available (GA) and deprecated. On each endpoint on the OpenAPI-Specification and also within this documentation we mark endpoints, data models or features by their release life cycle. These are included as flags (see details in the corresponding sections)

In this document we explain what each status implies in terms of backward compatibility, SLAs and general usage.

Alpha

Alpha endpoints are currently in development and might be not be fully functional. Therefore, breaking changes (both semantic and syntactical) are common. We change these endpoints without communication. Additionally, alpha endpoints are not contained in our SLAs.

Please contact us if you want to use endpoints marked with the alpha tag.

Alpha Flag

Beta

Endpoints with the beta life cycle state are more mature but still in active development. We try to prevent breaking changes. Nevertheless, breaking changes are possible in rare cases. There exists already functionality at these endpoints but we don't cover these in our SLA's. Breaking changes are communicated to clients two weeks before the change.

Please contact us if you want to use endpoints marked with the beta tag.

Beta Flag

General Available (GA)

Endpoints without any flag are production ready and stable endpoints. We serve these endpoints within our SLAs.

Deprecated

In some cases we might deprecate endpoints or attributes. We give hints on deprecated endpoints which endpoint or attribute has replaced this functionality. We are monitoring deprecated endpoints to make sure that we only remove functionality, when nobody is using it anymore. Deprecated endpoints are still served within our SLAs.

Overview

Endpoint State	SLAs	breaking changes	notification on changes
alpha	no	common	no
beta	no	rarely	yes, two weeks before change
General Available (GA)	yes	no	-
Deprecated	yes	no	-

Breaking Changes

When an endpoint is under active development (e.g. marked as alpha or beta) we might change its semantic and/or syntactic behavior. You will find alpha or beta flags on resources, types (or part of types) and a few other places which are under development. If you encounter such a flag it means the following:

• this endpoint, type, etc. might be subject to breaking changes in the future

• it might not be available at all times

• it could disappear without specific warning

• it currently does not fall under our SLA regulations

There are a lot enumerations in the OpenAPI Spec to ease the use of specific values for statuses, etc., for example:

OrderStatus:
  type: "string"
  enum:
    - "OPEN"
    - "CANCELLED"
    - "LOCKED

Please be aware that adding a value to it is considered a non breaking change (as described API Versioning). It happens very rarely, but it could happen that another value is added to an enumeration.

However, the tooling around this kind of "exceptional" use of enumerations is not very good: A code generator will most likely produce enumerations which cannot contain different values than the one described. This is why most of the enumerations also carry a BETA-Flag: To make this behaviour more apparent. If you are handling enumerations best practice is to anticipate this kind of behavior and map unknown enum values to one that you recognize or yield an error.