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 #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.

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.