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.
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.
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:
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.
Last updated
