Breaking changes
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.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.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.
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. |
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. |
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. |
Last modified 3mo ago