The major version is in the path: /v1. An integration written for /v1 keeps working, unchanged, for as long as /v1 exists.
What may change within /v1
- New operations, new scopes.
- New optional parameters, new fields in responses.
- New enum values (a status, a vehicle type, a brand), new error codes for new cases.
What never changes within /v1
- An operation, a field or a scope never disappears, and never changes its name or type.
- An optional parameter never becomes required; validation never gets stricter.
- An error code keeps its meaning; a unit (thousandths of a euro, cents) never changes.
The Floweet-Version header
Every response carries Floweet-Version, the version of the contract that served it (today 1.0.0-beta.1). Quote it with X-Request-Id when you report unexpected behavior.
A breaking change: /v2
If a breaking change becomes necessary, it ships in a new version, /v2, and /v1 keeps working for at least 12 months afterwards. An operation scheduled for removal will be marked deprecated in the contract, and the organizations still calling it will be told by e-mail.
During the beta
The API is in beta (contract 1.0.0-beta.1): the 1.0.0 contract will be frozen before the first live key is opened, and the compatibility rule above will apply from then on. Until then, every change is dated in the changelog.