API - Getting started

To get you started here are a step by step description what you need to do.

1. Create a token to get access to the API
2. List of available indicators
3. Collect the scores
4. Post the scores to KPI Dashboard

Create a token to get access to the API

Use of the API is always through an existing user in KPI Dashboard. There’s no special API user. You get to see and work with what the user you are logging in to the API is allowed to. please make sure the user has at least “Power User” rule.

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.

List of available indicators

To send HTTP request I use a command line tool called curl. It is available on a great many platforms and can be downloaded from http://curl.haxx.se/

So to get a list of indicators available in KPI Dashboard would run the following command:

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

The response would be in the form of XML. You should see it as output of you curl command right now. Or you can take a look at an example response if you prefer.

Important here is to capture the element id. you will need this when you post your score (step 4).

Collect the scores

At this point you have a list of indicators. For each indicator you now need to collect the score. A score is the value of an indicator at a given date. Collect the score from your local resources you have access to. For example you could do this by running a sql statement against your local database.

Post the scores to KPI Dashboard

Now you have indicators and their scores.
For example:

• indicator “Server Uptime” with id=12345
• score of 100% on 01 september, 2010

To send this score to KPI Dashboard you will need to POST the following XML to
https://dashboard.kpilibrary.com/api/v2/indicators/12345/scores.xml

<?xml version="1.0" encoding="UTF-8"?>
<score>
  <value>100</value>
  <date>2010-09-01</date>
</score>

With curl this would look like:

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
     -d "XML-FROM-ABOVE"  https://dashboard.kpilibrary.com/api/v2/indicators/12345/scores.xml

Alternatively you could send it like:

curl -u TOKEN:x -X POST \
 https://dashboard.kpilibrary.com/api/v2/indicators/12345/scores.xml?value=100&date=2010-09-01

Please note that you can send one (1) score at a time to KPI Dashboard. To upload five scores you would need to do five HTTP request.