Kumulos offers a RESTful interface to the data stored in your tables. It is accessible over SSL with a REST API key for your application. Each application may have multiple REST API keys with different combinations of permissions.

REST API key permissions available are:

  • Create (POST)
  • Read (GET)
  • Update (PUT)
  • Delete (DELETE)

N.B. The REST API keys are different to the application's API key on the application dashboard.

Format

The REST API accepts and responds in JSON. Your client should send an HTTP Accept header which includes json or */*.

URL Pattern

Kumulos's REST endpoint template is https://api.kumulos.com/v1/data/{tableAlias}/{id} where {tableAlias} is replaced with your application's table alias.

The {id} parameter is optional on GET requests, ignored on POST requests, and required on PUT and DELETE requests.

N.B. Your table's alias is your table's name with a numeric prefix. To identify the alias for your table, examine the URL from the 'browse' window on the Kumulos dashboard, tableAlias is included there.

Authentication

Authentication is performed by HTTP Basic Auth, where you set the username to your REST API key.

N.B. You do not need to specify a password, but any value will be accepted if you must pass one to your client.

Examples

All examples provided will use a table called Users with alias 1_27_users. It has the following JSON structure:

{
    "username": "Example",
    "userID": 12,
    "timeCreated": "",
    "timeUpdated": ""
}

Authentication is assumed to be correct in all examples.

Supported Operations

Create

POST requests issued with a valid JSON body matching your table's field structure will result in a new record being created. An HTTP 201 No Content response will be made with a Location header pointing to the newly created record.

For example:

POST https://api.kumulos.com/v1/data/1_27_users
Accept: application/json
Content-Type: application/json
{
    "username": "New user"
}

Returns URL of new user in Location header: https://api.kumulos.com/v1/data/1_27_users/12.

Read

To fetch a record or set of records, a GET request should be made against the desired endpoint. If the id is included, a single record will be returned. There is no 'wrapper' object, and the responses will be your record object or an array of record objects.

Paging

To control the paging, you can pass the following parameters:

  • page - The desired page (default: 1)
  • numberPerPage - The desired number of records per page (default: 50, max: 1000)

These should be passed as GET variables on the endpoint URL.

Sorting

To control the order of returned results, you can pass the sortBy parameter:

  • sortBy - Field name to sort by, prefix - to reverse sort direction

For example, fetch users, page 2:

GET https://api.kumulos.com/v1/data/1_27_users?page=2

For example, fetch user ID 12:

GET https://api.kumulos.com/v1/data/1_27_users/12

Update

To update a record, make a PUT request to the endpoint including the record's ID. The body should contain the JSON record for the updated fields (or all fields). This API will respond with the full JSON record after update.

For example:

PUT https://api.kumulos.com/v1/data/1_27_users/12
Accept: application/json
Content-Type: application/json
{
    "username": "Updated username"
}

Delete

A record can be deleted by making a DELETE request to the endpoint including the record's ID. An HTTP 201 No Content will be retuend on success.

For example:

DELETE https://api.kumulos.com/v1/data/1_27_users/12

Errors

Errors will be communicated to the client by the use of HTTP status codes. the 4xx and 5xx ranges indicate an error state. The resulting response will be a JSON object containing further information about the error.

Support

If you encounter any bugs or issues, please email [email protected] including your REST API key and the steps to reproduce your problem.