Rest
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.