Getting Started

A step-by-step guide to access your data using the API.

1. Familiarize yourself with REST and JSON

If you haven't worked with an API based on the REST architecture or JSON data format, you might want to read up on that before you proceed. Some recommended reading:

2. Create an API key

Head over to the API settings page to create an API key. All you need to fill out is an application name, the rest will be pre-filled. You can just call it My API Test or something like that for now.

3. Connect to the API

Get the tools

Although you're probably not going to build your final integration with it, using the command-line tool curl is a great way of testing HTTP-based communications. It also provides a clear and concise way for us to provide common examples throughout this documentation. Curl is available on all major platforms:

  • Mac OSX - it's included
  • Linux - depending on your distribution, it should be included or available in your package manager
  • Windows - you can download it here

Once you've completed the examples here you can, of course, use your platform/language of choice to connect to the API using one of the many REST client libraries out there.

Hello World!

Start by accessing a resource that doesn't require an API key: 

curl -i https://app.coredination.net/api/1/version

HTTP/1.1 200 OK
Content-Type: application/json

{"id":"2014-03-18_22-49-26","builduser":"jenkins","version":"2180"}

import requests
re = requests.get('https://app.coredination.net/api/1/version')
print re.json()
# {u'builduser': u'jenkins', u'version': u'2183', u'id': u'2014-03-19_16-58-50'}

Now try to access that resource with your API key as a query parameter: 

curl -i 'https://app.coredination.net/api/1/version?api_key={my-api-key}'

import requests
re = requests.get('https://app.coredination.net/api/1/version?api_key={my-api-key}')
print re.json()
# {u'builduser': u'jenkins', u'version': u'2183', u'id': u'2014-03-19_16-58-50'}

You should receive the same response as without the API key. If there's something wrong with your API key, you'll get a response like this: 

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Invalid API key

You can also keep URLs cleaner by sending your API key in a header: 

curl -i 'https://app.coredination.net/api/1/version' -H 'API-Key: {my-api-key}'

import requests
re = requests.get('https://app.coredination.net/api/1/version', headers={ 'API-Key': '{my-api-key}'})
print re.json()
# {u'builduser': u'jenkins', u'version': u'2183', u'id': u'2014-03-19_16-58-50'}

4. Get jobs

Let's GET the jobs list. You will get a little or a lot of JSON data back, depending on how many jobs you have. 

curl -i 'https://app.coredination.net/api/1/job' -H 'API-Key: {my-api-key}'

import requests
re = requests.get('https://app.coredination.net/api/1/job', headers={ 'API-Key': '{my-api-key}'})
print "Got " + str(len(re.json())) + " jobs"

5. Create a job

Now go ahead and create, POST, the simplest possible job. You will get the created job in JSON as a response. 

curl -i 'https://app.coredination.net/api/1/job' \
	-H 'API-Key: {my-api-key}' \
	-H 'Content-Type: application/json' \
	-X POST \
	-d '{ "title": "API Test" }'

import json, requests

job = { 'title': 'API Test' }
headers = { 'API-Key': '{my-api-key}', 'Content-Type': 'application/json' }
re = requests.post('https://app.coredination.net/api/1/job', data=json.dumps(job), headers=headers)
job = re.json()
print "The created job has ID " + str(job['id'])

Once you've done that successfully, you should find the created job in the jobs list. The job will be a draft, shown with gray text on white background. Make sure you haven't filtered out drafts and that you're viewing the All jobs list. If you can't find it, try searching.

Congratulations, you now have the power to import/export/synchronize data via the API!