This documentation describes the possibilities and processes surrounding the KOBAS API. This API is intended for use by technical teams working for or acting on behalf of companies who use the KOBAS Cloud back of house hospitality management software.
The KAPI is RESTful and operates over HTTPS, exchanging data using JSON. No other notation or transfer protocol is supported at this time. The KAPI is not available over HTTP without SSL/TLS encryption.
The KAPI relies on a secret key and nonce authentication process. The secret key is never transferred over the API, but is instead salted with a nonce and other HTTP headers, and then one-way hashed, before being sent in the HTTP headers of each KAPI request. The nonce is also transmitted within the header in clear text. As the secret key is also known by our servers, it is possible to perform the same salting and hashing to verify that the request is authorised.
This has the advantage that no credentials are transmitted in each request that could be lost or otherwise compromised. The nonce also guards against replay attacks.
Each KOBAS account will be issued an account id “CID” and a secret key “hash”.
The HTTP header must contain the following name/value pairs in the format:
Required headers with example values:
Date: Wed, 22 Jan 2014 17:49:47 GMT\r\n
These headers should be transmitted as-is, but they should also be used as a salt along with the hash (that must never be transmitted) in order to assemble the value of an additional header “Authorization”. The authorization value can be calculated with a sha1 hash of:
Date: Wed, 22 Jan 2014 17:49:47 GMT X-KAPI-CID: 1234 X-KAPI-NONCE: cdc453d075006b5bc8ec75e61f892953e0bf2062hashvalue
So the line feed and carriage return characters are removed, then the headers are concatenated and the security hash is added to the end. The result of the sha1 of this string should be appended as an additional header as follows:
The KOBAS servers will inspect the Date, X-KAPI-CID and X-KAPI-NONCE headers and perform the same operation to verify the authorization header. So long as this computes and the nonce is unique, the request will be accepted.
KOBAS offers a PHP library to perform this authentication upon request.
All HTTPS requests should be directed to: https://api.kobas.co.uk/ with an appropriate verb and endpoint.
The KAPI exposes a number of endpoints for data exchange and activity. Please see the full list of endpoints in the olive navigation box for details.
The KAPI accepts the following verbs:
The KAPI will accept a PUT request that creates a new resource at the specified location. If a resource already exists at that location, it will be overwritten. A POST request must never attempt to specify a location.
DELETE and GET requests expect data in the query string. POST and PUT requests expect information in the request body.
POST and PUT requests should be in one of the following formats, with a valid Content-Type header to match:
The KAPI servers support gzip compression and customers are urged to use this where possible to minimise bandwidth usage for all concerned.