Breaking changes

Introduction

We improve our API continuously, but in some cases, we need to make changes that are not fully compatible with the current interface. Recently we improved validation that should help both to unify rules for the entities and to maintain better integrity of the user data.

We want to make the implementation of the new API changes as simple as possible. You can start using the planned changes right now just by adding the Allow-Version key with the BC tag into your request headers and test the improved API ahead of the forced rollout.

Breaking changes #2 (`BC2`)

Planned rollout date: not scheduled yet

You can send requests with the HTTP header Allow-Version: BC2 to enable BC2 and test the changes ahead of the forced rollout.

Product endpoints: `externalId` is replaced by `externalIds`

The Product field externalId (a single string) is being replaced by the field externalIds (a list of strings). During this transition phase, the list is limited to 1 item at maximum and both fields share the same stored value: a value written through either field reads back through the other one.

Header now	After rollout	Validation
(none) or BC1	BC0 or BC1	Requests may change only the old field `externalId`; sending `externalIds` returns an error `400 Bad Request` (except `"externalIds": null` on POST, which is accepted and ignored, so a GET response containing the null field can be echoed back as a POST body). Responses contain both `externalId` and `externalIds`.
BC2	BC2 or (none)	Requests may change only the new field `externalIds` (at most 1 item, each up to 256 characters); sending `externalId` on PUT or PATCH returns an error `400 Bad Request` (on POST the field is silently ignored). Responses contain only `externalIds`.

Breaking changes #1 (`BC1`)

Planned rollout date: 2023-06-01

Before the rollout date, you can send requests with the HTTP header Allow-Version: BC1 to enable BC1. After this date, the API2 will behave as if the flag BC1 was set by default and it will not be needed in the headers. For backward compatibility, you will be able to use BC0 flag to switch back to previous behavior.

GET requests returning paginated data

The BC1 affects GET endpoints returning paginated list of entities. If there are no entities matching the filter or there are no entities at all, the response can be one of these:

Header now	After rollout	Validation
(none)	(none) or BC0	The endpoints return status 404 and empty BODY.
BC1	BC1	The endpoints return status 200 and BODY with JSON pagination structure and no data (`"totalItemsCount": "0"`). This change might simplify the implementation for some clients.

Info

For backward compatibility, the flag BC1 will not be applied on paginated endpoints by default after the rollout date. Nevertheless you can still use BC1 in the headers to change the validation after the rollout date.

Customer endpoints

The BC1 changes the validation of the field flags. This must be considered when creating a new customer by the POST method.

Header now	After rollout	Validation
(none)	BC0	The `flags` field is optional so it can be omitted or null.
BC1	BC1 or (none)	The `flags` field is required. Make sure the JSON structure contains `"flags": 0` or `"flags": "0"` to imply there are no flags.

Employee endpoints

The BC1 changes the validation if the employee is an administrator (i.e. if Employee.id == 0). Regardless of the BC1 flag, the administrator cannot be deleted (error: 403 Forbidden).

Header now	After rollout	Validation
(none)	BC0	The following values are ignored when updating: `enabled` (forced `true`), `deleted` (forced `false`), `accessLevel` (forced all rights), `stockAccessLevel` (forced all rights).
BC1	BC1 or (none)	Only the default (unchanged) values are accepted on update. If any value (`enabled`, `deleted`, `accessLevel`, `stockAccessLevel`) is changed, an error `400 Bad Request` is returned.

Category and Product endpoints

The BC1 changes validation of the VAT (field vat) for the Category and Product entities when the Cloud is configured for a tax-payer.

Header now	After rollout	Validation
(none)	BC0	The VAT is not validated.
BC1	BC1 or (none)	The VAT is validated for tax-payers and if it is not one of the configured VAT rates for the Cloud, an error `400 Bad Request` is returned. See the Tax endpoints documentation to configure the VAT rates for the Cloud.