Versioning and support

This version of the Cibusy API is v1, and every path starts with /public/v1. This guide covers what never changes under v1, what may be added, and how to get help with your integration.

What stays fixed under v1#

Under v1 nothing is removed and nothing is renamed. A property, a value or a status code you rely on stays as it is.

A change that would break that promise is not made under v1: it ships as a new version, under /public/v2, beside v1.

What may be added#

Under v1 things are only added:

• An answer may gain new properties.
• An enum, such as an order status, an order type or a unit, may gain new values.
• New endpoints may appear.

Write your code for that: ignore the properties you do not know, and handle a value you do not know in a way that does not break you. For example, when you show an order's status, fall back to a general phrase for a value you have not seen:

const STATUS_LABELS = {
  Received: 'Order received',
  Preparing: 'Being prepared',
  Ready: 'Ready',
  Served: 'Served',
  OnTheWay: 'On its way',
  Completed: 'Completed',
  Cancelled: 'Cancelled',
};

function statusLabel(status) {
  // A value added to v1 later still gets a sensible label.
  return STATUS_LABELS[status] ?? 'Order updated';
}

If you validate answers against a strict schema, allow extra properties, so a new property does not break your code.

The OpenAPI document#

The OpenAPI 3 document that describes every endpoint and field of the API is at:

https://api.cibusy.com/developers/openapi/v1.json

Use it to generate a client or type definitions in your language. The bodies of the webhook events are in it too, as the schemas OrderUpdatedWebhookEvent, ReservationUpdatedWebhookEvent and TestWebhookEvent. The API reference on this site is built from the same document.

Support#

For help with an integration, write to support@cibusy.com from the venue's own email address, and say which venue it is. Include:

• The traceId of the error, when it has one: it lets us find the request in our logs.
• The id of the order you mean.
• When the request was made, which endpoint it went to and the errorCode you received.

Never put your API key or webhook secret in an email: the traceId and the id of the order or reservation are all we need to find the request.