Sections

DataCollector

API

Sample code

KPI Dashboard API

The KPI Dashboard API is a simple and secure interface for accessing your KPI Dashboard account data using plain XML or JSON over HTTP using all four REST commands — GET, POST, PUT and DELETE.

With this interface you can easily upload your organization’s scores. For example, you can use the API to integrate snapshots taken from your organization’s ERP, finance or other systems with KPI Dashboard.

The API also makes it easy to create web and desktop applications that integrate with your account.

Service URL

The KPI Dashboard API has a single point of entry:

https://dashboard.kpilibrary.com/api/v2/

Please note the use of https:// in the URL above. All KPI Dashboard API communication is encrypted over HTTPS. Any non-secure requests are automatically rejected, so we recommend establishing a test connection with the secure API entry point before sending sensitive data.

Authentication

Use of the API is always through an existing user in KPI Dashboard. There’s no special API user. What you can do with the API (the data you see and privileges on that data) depends on the authorization of the user account you are using when accessing the API. You’re required to use an API Authentication Token via HTTP Basic Authentication. Security is provided via SSL.

Each user has it’s own API Authentication Token. To retrieve your token which you need in order to make API calls follow these steps:

  1. Log into KPI Dashboard as the user that will be making the API calls.
  2. Select “Settings” at the upper-right corner of any page, then select “Personal Settings”.
  3. Click on the link “Reveal my API token”. If no token had been generated yet, click on the “Generate token” button. Use the token that is revealed.

When you call the KPI Dashboard API use the token as the username and use anything as a password in the HTTP Basic Authentication handshake.

For example, suppose your token is cksmxydsuwltfuf, using the curl command line client we can issue this command:

curl -u cksmxydsuwltfuf:x https://dashboard.kpilibrary.com/api/v2/indicators.xml

Note that it’s not necessary to send a password. It’s often easier just to pass in a dummy password. In all the examples we send a password with value x.

Guard your API token as you would any username and password. If you fear someone else got hold of your API token you can simply generate a new token by clicking again on the “Generate token” button on the “Personal Settings” page. After doing that make sure to update your clients with the new token.

Note that the /me.xml endpoint is the one exception to token authentication: you can use a username and password to authenticate against this action. This allows developers to obtain the token for a user, given that user’s username and password, which makes it easier for users to authenticate on mobile platforms and the like.

Request Limits

By default, all accounts have a request limit of 3,600 API request per hour and 20,000 API requests per day. Additionally, by default a maximum of 100 results will be returned for list methods, regardless of the value sent with the per_page parameter.

When your client exceeds the rate limit you will get an HTTP 403 response code and a response body with an appropriate “Rate Limit Exceeded” message.

We encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).

Pagination

All list results are paginated. By default 20 results are returned in lists. Use the per_page parameter to request more results per page. By default the maximum value allowed for per_page is 100. Use the page parameter to request a specific page in the total result set.

The response headers will contain values for the following keys: X-TotalPages, X-PerPage, X-CurrentPage.

For example:

Request

curl -u TOKEN:x https://dashboard.kpilibrary.com/api/v2/breakdowns.xml?page=2&per_page=50

Response

Status: 200

X-CurrentPage: 1
X-PerPage: 50
X-TotalPages: 2

<?xml version="1.0" encoding="UTF-8"?>
<breakdowns type="array">
  <breakdown>
    ...
  </breakdown>
  <breakdown>
    ...
  </breakdown>
  ...
</breakdowns>

XML Escaping, JSON Encoding and URL Encoding

KPI Dashboard supports passing data to the API as XML or JSON in the post body, or as URL parameters. You must properly escape your data depending on the method you use – XML escaping for XML, JSON encoding for JSON, and URL encoding for URL parameters.

An example of passing data via URL parameters to create an Indicator:

curl -u TOKEN:x -X POST \
  https://dashboard.kpilibrary.com/api/v2/indicators.xml?indicator\[name\]=Average%20Response%20Time

Representation Formats — XML

To send and retrieve API results as XML always simply end the URL of the request with .xml

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<indicator><name>Mean Time to Repair</name></indicator>" \
  https://dashboard.kpilibrary.com/api/v2/indicators.xml

Successful Response

Status: 201

<?xml version="1.0" encoding="UTF-8"?>
<indicator>
  <name>Mean Time to Repair</name>
  <id type="integer">128</id>
</indicator>

Failure Response

Status: 404

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Couldn't find Indicator with ID=129</error>
</errors>

Representation Formats — JSON

To send and retrieve API results as JSON always simply end the URL of the request with .json

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"name\": \"Mean Time to Repair\"}" \
  https://dashboard.kpilibrary.com/api/v2/indicators.json

Successful Response

Status: 201

{ "id": "128", "name": "Mean Time to Repair" }

Failure Response

Status: 404

{ "error": "Couldn't find Indicator with ID=129" }

JSON-P Callbacks

Based on JSON-P optionally a callback function can be specified with the parameter callback when sending requests that respond with JSON. For example, if a callback parameter with value parseResponse was sent, a result similar to the following will be emitted:

Request

curl -u TOKEN:x -X GET \
  https://dashboard.kpilibrary.com/api/v2/breakdowns/128.json?callback=parseResponse

Response

parseResponse({ :id => 128, :name => "Country", :indicators => [1,2] });

Note that the Content-Type of these callback responses will always be application/javascript, not application/json.

Errors

If there is an error in your API request, the response will be returned with an non-success HTTP Status Code.