Versioning and deprecation

What may change in the Plek API without notice, what never changes without notice, and how long deprecated parts keep working.

The Plek API has one version, the one documented here. It grows with the product: every feature that changes what staff can see or do updates the OpenAPI document this portal is built from, and a test fails when a new route has no documentation.

#Changes we make without notice

These are compatible; build your client to accept them:

• new routes, new optional request fields and new query parameters;
• new fields in responses, and new values in lists of objects;
• new error codes on existing statuses, and new webhook events (you only get events you subscribed to);
• new values of fields that are open-ended by nature (a booking source, a payment method): treat an unknown value as "other";
• changes to error messages (error), which are for people. Branch on code.

#Changes we announce first

• removing or renaming a route, a field or a value;
• changing a field's type or meaning, or making an optional request field required;
• tightening a rule that refuses requests that worked before (beyond fixing bugs and abuse).

A breaking change is announced at least six months ahead. Until then the old form keeps working; the route or field is marked deprecated in the reference with what replaces it. Security fixes may not wait that long.

#Widgets

The embed loader is versioned in its URL: /embed/v1/plek.js only takes compatible changes, and a breaking change would be a new /embed/v2/ next to it. See Embedding widgets.

#The OpenAPI document

The reference is generated from the code that serves the API (swagger-php attributes on the controllers), so the two don't drift. Download it as /openapi/plek.json, or per API: staff, public, customer. Not every route is described yet; the list shrinks with every release, and routes without a description are not part of the promise above.