Nitrobox provides a set of different APIs for our customers to consume in order to easily handle their business needs around Billing, Payment and Accounting.
This page provides information about our approach to API lifecycle management including versioning, deprecation policy and finally sunsetting of our APIs or elements of those if required.
API Versioning
For all APIs provided our teams ensure that each API remains stable and backward compatible with features added gradually without any breaking change.
Nonetheless, each Nitrobox API is versioned from the very beginning to be prepared for breaking changes once required. In an ever-changing world with regards to both business and technical aspects, an API must evolve to reflect those changes, to be maximally useful to our customers and to be easily integrated by them. API versioning paves the way to introduce backward incompatible changes and improvements by providing different versions of an API in parallel ensuring that existing clients continue to function as expected. This allows our customers to migrate from an earlier to the latest API version on their own schedule.
Nitrobox targets a maximum of two versions of an API to be available in parallel - the latest version and a deprecated version. This allows us to focus our development efforts on enhancing the latest API version introducing new valuable features for our customers only there while deprecating any prior API version reduces efforts for those to maintenance only.
Backward compatibility of a version is guaranteed only related to the on-the-wire representation of our API, which means for any payload sent or returned. For consumers generating code from our OpenAPI specification a once-generated API client will always stay compatible with the underlying API version. However, changes to the API definition might affect generated code even though done backward compatible as described above (e.g. schema re-organizations). So a consumer regenerating code to update its client to use new API features might be required to make minor changes to the client code without any semantics changed within the API.
What is a "Nitrobox API"?
A "Nitrobox API" refers to a collection of REST endpoints that serve a collective purpose. For example, our Customer API and our Contract API are different APIs each and separately versioned.
Deprecation and Sunsetting Policy
Deprecation is used to inform our customers that a complete API, a version of an API or elements of it (a resource, an endpoint, a query parameter or a resource property) are no longer recommended to be used but are still being completely operational, before finally being sunset at a later point in time which means being no more available for use.
During the deprecation period, we continue offering technical support for the deprecated elements without adding new features. We will almost always provide an equivalent substitute or introduce new functionality to make use of from then on. Therefore, new API clients must not start using APIs, API versions or any API element that have already been marked as deprecated.
To provide our customers with reasonable time to migrate, deprecations are announced 12 months before the end of support through official communication channels, including our changelog (RSS-Feed available as well), our API reference documentation and newsletters. However, 6 months after the initial deprecation announcement, we remove the deprecated elements from our publicly available documentation. Nitrobox will provide detailed migration guides from the very beginning accompanied by support from our Professional Services team to equip our customers with everything they need for a smooth transition.
Sunsetting will take place at the latest after the deprecation period of 12 months described above. This means the deprecated functionality is completely removed and can no longer be accessed, very likely to break at the client side without migrating in time. Already during the deprecation period we will monitor the API usage and may shut down the deprecated API element after all API clients have successfully migrated, but in any case no later than the sunset date announced.
Example
2020-11-19→ version 2 of the API consumed is the latest version2021-10-01→ new version 3 of the API consumed is officially announced and published, version 2 deprecation period of 12 months starts2022-10-01→ version 2 is removed and no longer available for clients (sunset date reached)
HTTP response headers
In addition to our official communication regarding deprecation and sunsetting to let people know, we will start to return specific HTTP response headers which can be actively monitored by our API clients to identify deprecated API endpoints this way as well:
| HTTP response header | Description | Reference |
|---|---|---|
deprecation | The Deprecation HTTP response header field describes the deprecation of the resource identified with the response it occurred within. It conveys the deprecation date, which may be in the future (the resource context will be deprecated at that date) or in the past (the resource context has been deprecated at that date). | RFC Deprecation HTTP Header |
sunset | The Sunset HTTP response header field allows a server to communicate the fact that a resource is expected to become unresponsive at a specific point in time. It provides information for clients that they can use to control their usage of the resource. The Sunset header field contains a single timestamp that advertises the point in time when the resource is expected to become unresponsive. | RFC 8594 - The Sunset HTTP Header Field |
Remarks:
- value for each header is a HTTP-date timestamp, as defined in Section 7.1.1.1 of [RFC7231])
- while the referenced RFCs define headers as
DeprecationandSunset(with capitalized first letter), RFC7540 for HTTP/2 states "...header field names are strings of ASCII characters that are compared in a case-insensitive fashion. However, header field names MUST be converted to lowercase prior to their encoding in HTTP/2..."
Example
deprecation: Fri, 01 Oct 2021 00:00:00 GMT
sunset: Sat, 01 Oct 2022 00:00:00 GMT