Show menu
Login

KOBAS API Documentation

The KOBAS API

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.

Definitions

  • HTTPS – Hyper Text Transfer Protocol Secure, the combination of SSL/TLS and HTTP resulting in a secure, stateless transfer of data over commonly used HTTP.
  • JSON – JavaScript Object Notation.
  • KAPI – KOBAS Application Programming Interface.
  • KOBAS Cloud – The KOBAS back of house Cloud based hospitality management software, delivered as a service.
  • KOBAS EPoS – The KOBAS front of house Electronic Point of Sale software and hardware.
  • RESTful – REpresentative State Transfer.

Technology

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.

Authentication

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.

Credentials

Each KOBAS account will be issued an account id “CID” and a secret key “hash”.

Example Authentication

The HTTP header must contain the following name/value pairs in the format:

NAME: VALUE\r\n

Required headers with example values:

Date: Wed, 22 Jan 2014 17:49:47 GMT\r\n
X-KAPI-CID: 1234\r\n
X-KAPI-NONCE: cdc453d075006b5bc8ec75e61f892953e0bf2062\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:

Authorization: hashresult\r\n

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.

Making Requests

All HTTPS requests should be directed to: https://api.kobas.co.uk/ with an appropriate verb and endpoint.

Endpoints

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.

Verbs

The KAPI accepts the following verbs:

  • DELETE
  • GET
  • POST
  • PUT

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.

Payload

DELETE and GET requests expect data in the query string. POST and PUT requests expect information in the request body.

Content-Type, Encoding and Compression

POST and PUT requests should be in one of the following formats, with a valid Content-Type header to match:

  • Content-Type: application/json
  • Content-Type: application/x-www-form-urlencoded

The KAPI servers support gzip compression and customers are urged to use this where possible to minimise bandwidth usage for all concerned.