Endpoint deprecation process
New features are continually being added to the CADMATIC Web API, which sometimes leads to existing endpoints becoming redundant or replaced by improved alternatives. To ensure our users have enough time to transition to the new endpoints, we follow a formal process. Initially, we mark any unnecessary endpoint as "deprecated". Subsequently, the endpoint is then scheduled for removal, a stage we refer to as "sunset". Finally, the endpoint is removed. This systematic approach allows for smooth transition and uninterrupted use of our API.
Deprecation
An endpoint that is deprecated is no longer receiving any updates, but still remains fully functional in the API.
Timeline for deprecation
An endpoint can get deprecated in a major release (T1–T3).
The deprecated endpoints are listed in the release notes.
HTTP header
Using a deprecated endpoint returns the following HTTP header in the response:
Deprecation: true
In addition, the "Link" header of the HTTP response has a link to this documentation page:
Link: <http://docs.cadmatic.org>; rel="deprecation", type=text/html
Note: The link header might also contain entries that are not related to the deprecation status.
Sunsetting
An endpoint that is sunset has a definite date after which the endpoint will be removed from the API. Until then, the endpoint is no longer receiving any updates, but still remains fully functional in the API.
For the users, the sunset date is not a fixed deadline: the endpoint keeps working until the user organization upgrades the Web API to a version that has been released after the sunset date.
Timeline for sunsetting
An endpoint can get sunset in the yearly T1 release, after being deprecated for some time.
The sunset endpoints are listed in the release notes.
HTTP header
Using a sunset endpoint returns the following kind of HTTP header in the response, in accordance with RFC 8594:
Sunset: HTTP-date
HTTP-date is defined in section-7.1.1.1 of RFC 7231. A real-world example of the response would look like this:
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
In addition, the "Link" header of the HTTP response has a link to this documentation page:
Link: <http://docs.cadmatic.org>; rel="sunset", type=text/html
Note: The link header might also contain entries that are not related to the sunsetting status.
Removal
An endpoint that has been removed provides an error response if used.
Timeline for removal
An endpoint can get removed in the yearly T1 release, after being sunset for one year.
The removed endpoints are listed in the release notes.