Skip to content

API

Jump to bottom
Richard Darst edited this page Jan 4, 2016 · 1 revision

This page documents the API of the koota server.

General

Device IDs are hex numbers of any length (up to 64 hex digits). The last two digits are check digits, to ensure that the number is entered correctly. This is because the data collection server does not necessarily have a full list of all allocated device_ids (because we are separating collection from personal data), and it would be good to have some way to verify that things are not mistyped. This is not a secure authentication, just a minor check.

For testing uploading with a fake device_id, use "1fe", "2fc", or "3fa". These will validate properly.

Hosts

koota.X is the primary host for user interaction. Data should be POSTed to data.koota.X. In both of these, X is the top level domain we are hosted under. For now, these two hosts have equivalent functions, but in the future, the data could be stored separate from the user interface.

Endpoints

/post

General POST URL for all data. Anything posted to this endpoint is stored in the database in same form it comes in. The only required parameter is device_id. This method handles data from various devices, so is rather flexible in the formatting of the data and will try to figure things out. Only the POST method is supported.

  • The device_id parameter can be passed several ways. The following are tested, and the first found device_id is used.
  1. Device-specific methods (described elsewhere)
  2. Device-ID: HTTP header. (the recommended method)
  3. device_id URL parameter (?device_id=XXXX)
  4. If the request body is a POSTed HTML form, then the device_id parameter within that form. (Not recommended)
  • The data can be found in several ways
  1. Device-specific methods (described elsewhere)
  2. The data field within a HTML POSTed form. (not recommended)
  3. The raw request body. (the recommended method)

Return value: JSON object {"ok": true}. If an error is found, return status 400 or 4xx and object with "ok"=false and "error"="<message>" and possibly other data.

/post/purple

POST endpoint for Purple Robot app. The logic is mostly the same as /post, but directs data to the purple robot handler, since it needs special treatment.

/config

Endpoint for configuration. device_id should be passed as in the /post endpoint. Currently only returns { }.

Clone this wiki locally