Skip to main content

Migration

Welcome to the Winston POS v2.0 API migration guide!

We're excited to announce version two of our API. This version update aims to be more predictable, robust, and developer-friendly. It includes stricter RESTful conventions, simplified payload structures, and it now relies on standard HTTP status codes for proper error handling.

This guide outlines all the breaking changes, endpoint relocations, and payload modifications you will need to update your integrations.

At a glance, the biggest changes include:

  • Bearer token authentication: API keys have moved from query parameters to the Authorization header.
  • Strict HTTP status codes: We have removed the redundant status: 'success' wrapper from almost all JSON responses. Success and failure are now strictly indicated by standard HTTP status codes (e.g., 200 OK, 400 Bad Request).
  • Cleaner payloads: We've flattened unnecessary data objects and renamed fields to be more intuitive and consistent across the board.

We know migrations can be a chore, but we highly recommend updating your integrations as soon as possible to take advantage of the improved reliability.

Missing anything, or running into unexpected issues? Feel free to contact our API support team.

Authentication​

Authentication is no longer handled via query parameters. The new API requires that the API key is provided through the Authorization HTTP header as a Token token (Authorization: Token <app_name>@<api_key>).

This is the same app name and API key as you would previously provide in the app_name and api_key query parameter, respectively (exception noted below).

Miscellaneous integrations​

The new API no longer supports API keys that had a corresponding app_name value of 'selforder'. The corresponding integration has also been marked as legacy in our backoffice.

The new API works with the new miscellaneous integration that requires you to sign up as an integrator before you can authenticate to our API. You can read here how that works.

If you are currently not using the 'selforder' app name, you don't have to do anything. The other integrations will still work with your existing API key.

Routes​

Below is the categorized list of route changes.

General / Collections​

  • Response changes: The /list/ and /:collectionName/ routes no longer returns the status field.

Schemas​

  • /schemas/
    • The data key in the response payload has been renamed to collections.
    • The status field has been removed.
  • /schemas/:collection/
    • The data key in the response payload has been renamed to schema.
    • The status field has been removed.
    • Error handling: Now correctly returns a non-200 HTTP status code on error instead of a 200 OK with a failed status payload.

Tenants​

  • /tenants/
    • The endpoint to create a tenant has been moved to /tenants/create.
    • The status field in the response has been removed.

Categories​

  • Endpoint relocation: The /categories/vatList/ route has been moved to /reporting/vatList/.
  • /categories/vatList/
    • The status field in the response has been removed.

List​

  • /list/
    • The status field has been removed.
    • The data field has been renamed to collections.
  • /:collectionName/
    • The status field has been removed.

Sync​

  • Endpoint relocation: The /:collectionName/sync routes have been moved to /sync/:collectionName.
  • /sync/
    • The status field has been removed.
    • The data field has been renamed to collections.
  • /sync/:collectionName/
    • The status field has been removed.

Reservations​

  • Removed endpoints:
    • /reservations/get (Use the /reservations route instead; do note that this route does not behave the exact same).
    • /reservations/remove (Use the /reservations/delete route instead).
    • /reservations/list (Use the /reservations route instead; do note that this route does not behave the exact same).
  • Error handling & response changes: The following routes no longer return true or false booleans. Instead, if no entries are updated/removed, they will return a 400 HTTP error code:
    • /reservations/update
    • /reservations/delete
    • /reservations/assignTable
    • /reservations/removeTable
    • /reservations/checkIn

Tables​

  • /tables/order
    • The status field has been removed.
    • The data field has been removed; the order object is now part of the root response object.
  • /tables/order/verify
    • Endpoint relocation: Moved to /tables/verifyOrder.
    • The status field has been removed.
    • The data field has been renamed to order.
  • /tables/pay
    • Request body: The _id field has been renamed to id.
    • The status field in the response has been removed.
Last updated on