Both Application Partner and Point of Sale (POS) APIs use hashed IDs and versioning extensively in order to validate input and also to avoid the potential for collision.
Here is a run down of the hashing we use, and how you can find or generate them yourself.
Location IDs
Hashed Location IDs are one of the most common hashes you'll need. From orders to reservations, they are used to associate the request with a given location.
Usage is in the header as doshii-location-id, as a URL parameter or in the body of a POST request depending on the endpoint.
These hashes cannot be generated by partner or POS, but can be found by performing GET /locations which will return a list of all locations and their hashed IDs. These IDs are static and do not need to be refreshed.
Organisation IDs
Hashed Organisation IDs are the next most common hashes you'll need. They are used to associate the request with a given organisation.
Usage of these hashes is always in the header as doshii-organisation-id where required by the endpoint.
These hashes cannot be generated by partner or POS, but can be found by performing GET /locations which will return a list of all locations and their not only their hashed locations IDs, but also their hashed organisation IDs! These IDs are also static and do not need to be refreshed.
POS Terminal IDs
Hashed Terminal IDs are used infrequently, but allow a POS to associate any action within the venue with the physical POS terminal. These terminals need to be registered in Doshii prior to referencing.
Usage is in the header as doshii-terminal-id, as a URL parameter or in the body of a POST request depending on the endpoint.
These hashes cannot be generated by partner or POS, but can be found by performing GET /terminals which will return a list of all terminals for a given location and their hashed IDs. These IDs are static and do not need to be refreshed.
App Device IDs
Hashed Device IDs are used infrequently, but allow an App to register specific devices within the App eco-system with Doshii, typically for the purposes of filtering Doshii events. These devices need to be registered in Doshii prior to referencing.
Usage is as a URL parameter or in the body of a POST request depending on the endpoint.
These hashes cannot be generated by partner or POS, but can be found by performing GET /devices which will return a list of all devices for a given App and their hashed IDs. These IDs are static and do not need to be refreshed.
Order Version
This is a special hash that exists on orders in the "version" field. Basically this hash exists to ensure that no orders are updated by mistake, or updated out of sync. Each time the order is changed, via a PUT /orders/:order-id for instance, there will be a NEW version hash. Which means the next person who tries to send an update with an old version, will receive an error! Which is good!
There are two main ways to get an order version. Either by performing a GET /orders/:order-id, or if you're using Doshii's WebSocket service you'll get a new version in an order_updated event automatically each time the order is updated. Definitely much easier to use the WebSocket service.
Transaction Version
Similarly to Order Version Hash, this is a special hash that exists on transactions in the "version" field. Basically this hash exists to ensure that no transactions are updated by mistake, or updated out of sync. Each time the transaction is changed, via a PUT /transactions/:transaction-id for instance, there will be a NEW version hash. Which means the next person who tries to send an update with an old version, will receive an error! Which is also good!
There are two main ways to get an transaction version. Either by performing a GET /transactions/:transaction-id, or if you're using Doshii's WebSocket service you'll get a new version in a transaction_updated event automatically each time the transaction is updated. Again, definitely much easier to use the WebSocket service.
Location Menu Last Version
These version hashes represent a point in time for a menu, it means that you can optionally add this to the query string for the endpoint GET /locations/:id/menu?lastVersion=:last-version-hash.
Querying using the lastVersion param will return 304 (No Changes) if the same version is found otherwise it will return 404 (Not Found) so the App knows that menu has changed. They can then pull/fetch the new menu.
Usage is only as part of a query string and only for the GET location/:id/menu endpoint.
The version hash used here also cannot be generated, but can be found in the version field from a GET /locations/:id/menu
Device Version
This is a special hash that exists on devices in the "version" field. Basically this hash exists to ensure that no devices are updated by mistake, or updated out of sync. Each time the device is changed, via a PUT /devices/:device-id for instance, there will be a NEW version hash. Which means the next person who tries to send an update with an old version, will receive an error! Which, again, is good!
The device version canbe obtained by calling GET /devices/:device-id.