Versioning and deprecation policy
The policy at a glance. The sections below give the details.
| Before the first customer is live | After the first customer is live | |
|---|---|---|
| What is breaking | The eight kinds of change in the closed list below. Every other change is an addition | The same |
| Notice of a breaking change | An entry in the change list and an e-mail at least 30 days before it reaches production, shorter only when a pilot client agrees in writing. Entries 1 to 9 follow the dates in each entry | No breaking changes within v1. What is to go is replaced by something new beside it |
| A deprecated endpoint | Answers with Deprecation and Link from the announcement. Closing it is a breaking change, with the notice above | Answers with Deprecation from the announcement and Sunset at least 6 months later, then 422 endpoint-closed for as long as v1 exists |
| A new major version | Not part of this phase | /api/v2/ only when a change cannot be an addition to v1, and v1 stays at least 12 months after v2 is in production |
| Security or the law | A shorter notice, decided case by case and explained in the entry | The same |
| Headers | Deprecation and Link to the entry on a deprecated or closed endpoint, and Sunset on a deprecated endpoint once its end date is set. See Where you see it below | The same |
This policy covers the OrderEx API that your systems call, every path under /api/v1/ on
https://api.orderex.se. The version is part of the path, and v1 is the current version. Webhook
payloads are versioned on their own, and changes to them are listed in the same
change list.
What is a breaking change?
A change to the API is breaking when it does any of the following. The list is closed: every other change is an addition.
- Removes or renames an endpoint, a query parameter, a field in a response, or a value of an enum that a client can send.
- Makes an optional field or parameter required, or adds a required one.
- Tightens validation, so that a call that works today is rejected: a shorter maximum length, a new rule or a new format.
- Changes the meaning, unit or format of an existing field, also when its name and type stay the same.
- Changes the status code of an outcome, or the
typeof an existing error response, also when only the domain intypechanges. - Changes what is needed to authenticate or to be authorized, for example that an existing API key needs a new scope.
- Changes how
Idempotency-Keyor retries behave for a call that already supports them. - Changes the default value used when a field is left out, or the documented sort order of a list.
What is an addition, and what must your client tolerate?
Additions are not breaking, and each one gets an entry in the change list: new
endpoints, new optional fields and parameters in requests, new fields in responses, new values of
an enum that only occurs in responses, new headers, new extension members in Problem Details, new
type values on new endpoints, and less strict validation.
So your client must:
- ignore fields in a response that it does not know,
- handle an enum value in a response that it does not know as other,
- handle a problem
typethat it does not know by its HTTP status code, - not depend on the order of the fields in JSON.
How is a breaking change announced?
An announcement is an entry in the change list, published on this portal, and an e-mail with the entry to the technical contacts of the clients we know. The entry's date is the date of the announcement.
Before OrderEx's first customer is live in production
- Entries 1 to 9 of the change list move v1 to the current order model, and each follows the dates in its entry. A further breaking change that belongs to this move is announced the same way, with its own entry in the change list.
- Every other breaking change gets an entry in the change list and is announced to the pilot clients we know at least 30 days before it reaches production. A pilot client that agrees in writing to a shorter time can get it.
After OrderEx's first customer is live in production
- No breaking changes within v1. What is to go is replaced by something new beside it, such as a new endpoint or a new field.
- An endpoint that is deprecated answers with
Deprecationfrom the announcement on, and withSunsetat least 6 months after the announcement. AfterSunsetit is closed: it answers 422endpoint-closed, whosereplacedBynames what replaces it, for as long as v1 exists. - A field that is deprecated is marked
deprecated: truein the schema in the OpenAPI document and gets an entry. It stays in the response for as long as v1 exists, since a header cannot say which field it means. - A new major version,
/api/v2/, comes only when a change cannot be made as an addition to v1. v1 then stays at least 12 months after v2 is in production, and every response from v1 carriesDeprecationandSunsetduring that time.
What if security or the law requires a change?
In both phases, a change that security or the law requires can be made with a shorter notice. OrderEx decides such an exception case by case, the entry says why, and the announcement is made as early as possible.
Where you see it
| State | Response | Headers | OpenAPI document |
|---|---|---|---|
| Deprecated, still works | As before | Deprecation: @<unix seconds> (RFC 9745). Sunset: <IMF-fixdate> (RFC 8594) when an end date is set. Link: <entry>; rel="deprecation" and, with Sunset, Link: <entry>; rel="sunset" | deprecated: true, and the entry's address in the operation's description |
| Closed | 422 endpoint-closed with replacedBy | Deprecation and Link with rel="deprecation". No Sunset, since the date has passed | deprecated: true |
<entry>is the address of the endpoint's entry in the change list on this portal, such ashttps://developers.orderex.se/changelog/0007-quantities-reported-as-facts.Deprecationis the moment the endpoint is or becomes deprecated, which can lie in the future.- Every response a deprecated endpoint itself produces carries the headers, errors included, such as a 400 for a request that could not be read. A response given before the endpoint is reached does not: a 401 or 403 because the API key or token is missing or wrong, or a 404 or 405 for a request that matches no endpoint.
- The change list lists every change, breaking or not, and the description of the OpenAPI document repeats it.
For example, a 204 from an endpoint that is deprecated and still works carries these headers:
Deprecation: @1798761600
Link: <https://developers.orderex.se/changelog/0007-quantities-reported-as-facts>; rel="deprecation"