Json

This service takes POST requests and returns the API method responses as JSON strings.

Accessing the JSON API

Kumulos’ JSON API can be reached by issuing POST requests to the following URL:

https://api.kumulos.com/b2.2/yourAPIKey/yourMethodTitle.json

The API key is available from the application dashboard. The method title can be seen on the API Method tab of the application dashboard in Kumulos converted to lowerCamelCase.

Using plist instead of JSON

If you would prefer to use plist rather than JSON, change the URL to

https://api.kumulos.com/b2.2/yourAPIKey/yourMethodTitle.plist

POST Request

Content Type

The Content-Type header is expected to be application/x-www-form-urlencoded, whilst the response will be in JSON (and so you can optionally set the Accept header to application/json).

Authentication

To authenticate, the HTTP Basic auth scheme is used. The username should be set to your Kumulos app's API key and the password should be set to your Kumulos app's secret key. Both of these can be found in App Dashboard.

The username and password should be concatenated with a single colon and the resultant string base64 encoded. This field is then included as the Authorization HTTP header prefixed by Basic as follows:

Authorization: Basic base64Encode(apiKey:secretKey)

Parameters

You need to send a params dictionary in the POST body. This is a key, value pair array of your method’s input parameters. If you’re unsure of what these are, they can be seen when you run a method in Kumulos’ control panel.

Examples

cURL

Given the method 'getNewPhotographers', that takes the parameter 'timeCreated', an example using cURL would be:

curl -X POST
     -H "Content-Type: application/x-www-form-urlencoded"
     -H "Accept: application/json"
     -H "Authorization: Basic base64EncodedUsername:Password"
     -H "Cache-Control: no-cache"
     -d 'params[photos]=1
         &params[timeCreated]=1462060800'
    "https://api.kumulos.com/b2.2/yourAPIKey/getNewPhotographers.json"

PHP

Given the same method 'getNewPhotographers' with parameter 'timeCreated', an example using PHP would be:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.kumulos.com/b2.2/yourAPIKey/getNewPhotographers.json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "params[photos]=1&params[timeCreated]=1462060800",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded",
    "accept: application/json",
    "authorization: Basic base64EncodedUsername:Password"
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

JSON Response Format

Kumulos will return a JSON object of the following format:

{
    "responseCode": 1,
    "responseMessage": "Success",
    "payload": [],
    "requestedMethod": "yourMethodTitle",
    "requestedFormat": "json",
    "timestamp": 1310549991,
    "requestReceivedTime": 1310549991,
    "maxAllowedRequestTime": 40,
    "requestProcessingTime": 0.061157941818237
}

The records or method response content will be in the payload key. If the responseCode is anything other than 1, it indicates an error. The error message will be in the responseMessage key and can provide more debugging information so it may be useful to log it to the console whilst developing your app.

Handling Data Fields

Kumulos stores data fields as base64 encoded data, so if you receive data from Kumulos, you will have to base64 decode it to access the original data. Similarly, when you send data to Kumulos, you should base64 encode it before transport.