Updated Jun 23, 2008 by purzelrakete

DetailedAPIDescription

Here you can find all Resources (these are things like Event, Event Series) that can be manipulated by the API.

General

There are some things that behave the same, no matter what Resource you're handling

Authentication

You can authenticate to boomloop using the following methods. Each request requires your consumer key. Actions such as creating events require you to have authenticated using OAuth, or HTTP Basic.

Consumer Key

After registering your application (http://boomloop.com/oauth/applications) you will receive a set of of keys. You need the Consumer Key to use the API.

Send the consumer key using the http header "X-Consumer-Key: dsc89blah_your_key"

If you're having troubles setting up headers, you can just add "?consumer_key=dsc89blah_your_key" to the end of the resource url.

boomloop uses OAuth (http://oauth.net/) as the recommended way of authenticating to the API. After registering your application you will receive a set of keys for use with OAuth. Please see oauth.net for instructions on how to authenticate.

HTTP Basic

It is also possible to use the API without OAuth. Just pass your credentials with the request, and remember to add your consumer key.

Pagination

All index resources are restricted to a certain number of results. You can skip to the next results by passing a &page=2 to the url. You can change the number of results per page by passing &per_page=100.

http://api.boomloop.com/events?page=4&per_page=80

This gets you event # 320 - 400.

Response Codes and Duplicates when creating Resources

After creating a Resource (ie an Event or a Place), a 201 HTTP Response code is returned with a Location Header containing the resource-url of the newly created Resource.

If, however, a duplicate was found, something like the following XML will be returned along with a 302 HTTP code and a Location header pointing to the duplicate:

'<?xml version="1.0" encoding="UTF-8"?>
<duplicates type="array">
  <duplicate>
    <resource-url>http://api.boomloop.com/event_series/81-feist-tour</resource-path>
  </duplicate>
</duplicates>'

Proprietary data

Some data on boomoop is imported from third parties that mandate their data to not be accessible by an API. Trying to GET such a Resource over the API will result in an HTTP 403 Forbidden being returned.

Events

The following resources are avaliable for events related calls.

Index

Location: http://api.boomloop.com/events, Http Method: GET, Requires Authentication: No,

Parameter

The following options filter or order results. They can be combined.

Show

Location: http://api.boomloop.com/

<event-identifier>

, Http Method: GET, Requires Authentication: Only for non-public events

Create

Location: http://api.boomloop.com/events, Http Method: POST, Requires Authentication: Yes, Curl Example:

curl -X POST -u vincent:secret -H 'X-Consumer-Key: klHgtzJ78jko7Jh7g' 'http://api.boomloop.com/events' -d '
<event>
  <description>Tanzabend im Hüpf</description>
  <place-resource-url>http://api.boomloop.com/places/234-huepf</place-resource-url>
  <event-series-resource-url>http://api.boomloop.com/event-series/23234-moo</event-series-resource-url>
  <start-hour>16:00</start-hour>
  <start-date>01.01.2010</start-date>
  <title>Tanzen im Hüpf</title>
</event>
'

Notes

You can send your own event identifier along with the create. just add a partner-id child node to the event node. Boomloop will save this metadata on the event.

Event Series

An Event Series bundles a releated series of events. The following resources are avaliable for event series.

Index

Location: http://api.boomloop.com/event_series, Http Method: GET, Requires Authentication: No

Show

Location: http://api.boomloop.com/

<event-series-identifier>

, Http Method: GET, Requires Authentication: Only for non-public event series

Notes

Associated Events are returned one page at a time. change this by adding a page parameter to the url: &page=2.

Create

Location: http://api.boomloop.com/event_series, Http Method: POST, Requires Authentication: Yes, Curl Example:

curl -X POST -u vincent:secret -H 'X-Consumer-Key: klHgtzJ78jko7Jh7g' 'http://api.boomloop.com/event_series' -d '
<event_series>
  <title>Feist Tour</title>
  <description>Feist Europe Tour. </description>
  <language>en</language>
  <website>http://feist.com</website>
</event_series>
'

Partner ID

You can send your own event identifier along with the create. just add a partner-id child node to the event_series node. Boomloop will save this metadata on the event series.

Connecting Events to the Event Series

Adding Events to your series is done by POSTing each event to /events. Add a node called event-series-resource-url with the event series url to connect the two. See above for details.

Ticket Categories

A event can have many ticket categories

Index

Location: http://api.boomloop.com/ticket_categories, Http Method: GET, Requires Authentication: No

Show

Location: http://api.boomloop.com/

<ticket-category-identifier>

, Http Method: GET, Requires Authentication: Only for non-public ticket_categories

Create

Location: http://api.boomloop.com/ticket_categories, Http Method: POST, Requires Authentication: Yes, Curl Example:

curl -X POST -u vincent:secret -H 'X-Consumer-Key: klHgtzJ78jko7Jh7g' 'http://api.boomloop.com/ticket_categories' -d '
<ticket-category>
  <short>1</short>
  <price>22.34</price>
  <currency>EUR</currency>
  <stock>1</stock>
  <link>http://buytickets.com/tickets/232891-feist-festhalle-frankfurt</link>
  <event-resource-url>http://api.boomloop.com/events/390-rocking-miss-frocky</event-resource-path>
</ticket-category>
'

Places

Create

Location: http://api.boomloop.com/<place identifier>, Http Method: POST, Requires Authentication: Yes, Curl Example:

curl -X POST -u vincent:secret -H 'X-Consumer-Key: klHgtzJ78jko7Jh7g' 'http://api.boomloop.com/places' -d '
<place>
  <name>Hüfp</name>
  <description>Hüpf till you schlüpf!</description>
  <complete_address>Rossmarkt 1, 60311 Frankfurt am Main</address>
  <category_id>100</category_id>
</place>
'