A Quick Start Guide
  • RSS Feed

Last modified on 9/28/2011 1:13 PM by User.

Tags:

A Quick Start Guide

All you need to develop for the Kiln API is an HTTP and a JSON library, so almost any language you're comfortable with will do. For this guide, we'll use Python as an example and assume you're comfortable with Python. Install Python 2.7 for your platform first. We'll be using the urllib2 module as our HTTP library and the json module as our JSON library.

Now run the interpreter.

Type "help", "copyright", "credits" or "license" for more information.

>>>

Determine the URL of your Kiln installation. If you're a Kiln On Demand user, it'll look like "http://username.kilnhg.com/". Otherwise, it should be the URL that ends in a forward slash that takes you to the Dashboard. And, if you append "Dashboard/Cases" to the end, it should be the URL that takes you to your cases. And, if you append "Api/1.0/" to the end, it becomes the prefix for all the API call URLs. We'll write a helper function in Python that prepends this URL since we'll be using it all the time.

>>> def api(url): return 'http://example.com/Kiln/Api/1.0/' + url

Note: If you are using Kiln On Demand, use "kilnhg.com" and do not include "/Kiln" in the URL:

>>> def api(url): return 'https://example.kilnhg.com/Api/1.0/' + url

Let's make a helper method to grab (or slurp, in Perl parlance) JSON and parse it for us.

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
>>> import json
>>> import urllib2
>>> from urllib import urlencode

>>> def slurp(url, params={}, post=False, raw=False):
    params = urlencode(params, doseq=True)
    handle = urllib2.urlopen(url, params) if post else urllib2.urlopen(url + '?' + params)
    content = handle.read()
    obj = content if raw else json.loads(content)
    handle.close()
    return obj

Since every request has to be authenticated, we might as well slurp a token.

>>> token = slurp(api('Auth/Login'), dict(sUser='Administrator', sPassword='fogcreek'))

You'll have to replace those strings with your own credentials. We're making an API call already! Specifically, we're making a call to "Api/{version}/Auth/Login". Consulting the documentation, we know that it takes a username and a password argument. We're also passing them to slurp(), which kindly URL encodes our arguments and handles the differences between GET and POST, as discussed in API Idioms.

With our token in hand, we can start make a new project and a new repository.

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
29:
>>> from pprint import pprint
>>> pprint(slurp(api('Project/Create'), dict(sName='New Project', permissionDefault='write', token=token)))
{u'ixProject': 2128,
 u'permissionDefault': u'write',
 u'repoGroups': [{u'ixProject': 2128,
                  u'ixRepoGroup': 2852,
                  u'repos': [],
                  u'sName': u'',
                  u'sSlug': u''}],
 u'sDescription': u'',
 u'sName': u'New Project',
 u'sSlug': u'New-Project'}
>>> pprint(slurp(api('Repo/Create'), dict(sName='New Repository', ixRepoGroup=2852, permissionDefault='write', token=token)))
{u'bytesSize': None,
 u'fCentral': True,
 u'ixParent': None,
 u'ixRepo': 434,
 u'ixRepoGroup': 2852,
 u'permissionDefault': u'write',
 u'personCreator': {u'ixPerson': 2,
                    u'sEmail': u'admin@example.com',
                    u'sName': u'Administrator'},
 u'repoBranches': [],
 u'sDescription': u'',
 u'sGroupSlug': u'Group',
 u'sName': u'New Repository',
 u'sProjectSlug': u'New-Project',
 u'sSlug': u'New-Repository',
 u'sStatus': u'new'}

Notice that, just like in Kiln, a new project comes with a new empty repository group. The other API calls are similar: Everything is done over HTTP and JSON, and you only need the flimsiest of wrappers to make it bearable.

Return to main documentation.