Skip to main content

Versioning and deprecation policy

The policy at a glance. The sections below give the details.

Before the first customer is liveAfter the first customer is live
What is breakingThe eight kinds of change in the closed list below. Every other change is an additionThe same
Notice of a breaking changeAn 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 entryNo breaking changes within v1. What is to go is replaced by something new beside it
A deprecated endpointAnswers with Deprecation and Link from the announcement. Closing it is a breaking change, with the notice aboveAnswers 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 versionNot 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 lawA shorter notice, decided case by case and explained in the entryThe same
HeadersDeprecation 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 belowThe 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.

  1. Removes or renames an endpoint, a query parameter, a field in a response, or a value of an enum that a client can send.
  2. Makes an optional field or parameter required, or adds a required one.
  3. Tightens validation, so that a call that works today is rejected: a shorter maximum length, a new rule or a new format.
  4. Changes the meaning, unit or format of an existing field, also when its name and type stay the same.
  5. Changes the status code of an outcome, or the type of an existing error response, also when only the domain in type changes.
  6. Changes what is needed to authenticate or to be authorized, for example that an existing API key needs a new scope.
  7. Changes how Idempotency-Key or retries behave for a call that already supports them.
  8. 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 type that 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 Deprecation from the announcement on, and with Sunset at least 6 months after the announcement. After Sunset it is closed: it answers 422 endpoint-closed, whose replacedBy names what replaces it, for as long as v1 exists.
  • A field that is deprecated is marked deprecated: true in 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 carries Deprecation and Sunset during 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​

StateResponseHeadersOpenAPI document
Deprecated, still worksAs beforeDeprecation: @<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
Closed422 endpoint-closed with replacedByDeprecation and Link with rel="deprecation". No Sunset, since the date has passeddeprecated: true
  • <entry> is the address of the endpoint's entry in the change list on this portal, such as https://developers.orderex.se/changelog/0007-quantities-reported-as-facts.
  • Deprecation is 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"