REST API

Introduction

Pukka Software (MotorsportReg.com) provides a RESTful API. If you wish to create a software application that uses our service, then you will need to know which resources are available, what their locations are, what methods each resource supports, and what the responses might be. All this information is available on this page.

Authentication

All API requests require a valid username and password to authenticate your requests. To obtain credentials, contact us.

For user agents that support it, we have a crossdomain.xml file located at http://api.pukkasoft.com/crossdomain.xml. We also respond to every request with the HTTP Header 'Access-Control' set to 'allow <*>'. This permits building mashups with our data from any domain.

Licesning & Attribution

Use of the API is subject to prior approval and may be revoked at any time without warning. Content that is displayed must include one of the following three snippets of code exactly as it appears and display the badge at its original size (190x30). We may provide other sizes upon request.

Resources and Locations

A REST interface presents resources at published locations. Here are the names locations of the Pukka Software REST API resources.

GET /rest/calendars
All events from all calendars starting today or later.
GET /rest/calendars/organization/{organization_id}
Return a calendar of events for a single organization/club (ProAutoSports, BMW CCA GGC, ...)
GET /rest/calendars/venue/{venue_id}
Return a calendar of events for a single venue (Laguna Seca, Road Atlanta, ...)
GET /rest/calendars/type/{type_id}
Return a calendar of events for a single type of event (HPDE, Autocross, Rally, ...)
GET /rest/events/{event_id}/assignments
Return a list of assignments (aka entries) for an event that handles registration through MSR
GET /rest/events/{event_id}/segments/{segment_id}/assignments
Return a list of assignments for a single segment of an event

Future updates will permit accessing details on organizations and venues as well as updating events for authorized clubs.

Status Codes

Each resource location supports a number of methods, which may send or receive a piece of data. All response codes are included in the HTTP Status response header. Possible status codes include:

Successful POST requests (e.g., to create a new invoice) will return a status code of 201, include a Location header with the URI of the newly-created resource, and include the XML representation of the resource in the body of the response.

Successful PUT requests (e.g., to update an existing invoice) will return a status code of 200, and include the XML representation of the resource in the body of the response.

Successful DELETE requests (e.g., to delete an existing invoice) will return a status code of 200, and no body.

Data Formats

If no format is specified, XML is the default. Most resources on api.pukkasoft.com support the following:

Name Format
application/vnd.pukkasoft+xml XML representation
application/vnd.pukkasoft+json JSON representation

Certain resources, notably calendars, also support the following:

Name Format
application/vnd.pukkasoft+rss RSS representation
application/vnd.pukkasoft+atom Atom representation
application/vnd.pukkasoft+calendar iCalendar/ics representation

Authorized Requests

All requests must be sent with a valid username and password or the request will be denied with a 401 Unauthorized response. You can pass a username and password to most HTTP libraries like in this example with cURL:

curl -u userid:password http://api.pukkasoft.com/rest/resource/etc

Most HTTP libraries will handle Basic Authentication details automatically. To do it manually, include an Authorization header with a value like Basic credentials, in every request. The credentials string should be the Base64-encoded version of the string userid:password. For example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

If your credentials are correct but you lack sufficient authorization, the request will be denied with a 403 Forbidden response.

Data Compression

Our REST API supports gzip/deflate compression for transmission. You can signal to our API you wish to receive compressed data by sending an additional header:

Header Value
Accept-Encodinggzip,deflate

Your software will need to decompress the data before using it (which may happen automatically). This is especially useful for the full events feed which can include more than 1000 events at a time and may be several megabytes uncompressed.

Example Interactions

Most developers use cURL to test and debug RESTful APIs. This is a simple command-line tool that you can use to get up to speed with our API. We will be providing code samples for common languages in the future.

To retrieve a representation, use the GET method. For example (using cURL's -X option to specify the request method):

curl -u userid:password -H 'Accept: application/vnd.pukkasoft+xml' \
    -X GET http://api.pukkasoft.com/rest/calendars

To create a new resource, use the POST method on a collection. The body of the request should be an XML or JSON representation of the member resources. For example, (using cURL's -d option to provide a request body):

curl -u userid:password -H 'Accept: application/vnd.pukkasoft+xml' \
    -d '<?xml version="1.0" encoding="UTF-8"?>XML Data' -X POST http://api.pukkasoft.com/rest/calendars

The PUT method changes existing resources. The body of the request should be an XML or JSON representation of the member resource. For example:

curl -u userid:password -H 'Accept: application/vnd.pukkasoft+xml' \
    -d '<?xml version="1.0" encoding="UTF-8"?>XML Data' -X PUT http://api.pukkasoft.com/rest/calendars/event_id

The DELETE method permanently removes a resource. For example:

curl -u userid:password -H 'Accept: application/vnd.pukkasoft+xml' \
    -X DELETE http://api.pukkasoft.com/rest/calendars/event_id

Note that in some cases, deleting a resource will cascade to related resources. For example, deleting an event will also delete the attendees associated with the event.

Because not all HTTP libraries support the PUT and DELETE methods, they can be tunneled through POST by including a _method query parameter in the request, with a value of either PUT or DELETE:

curl -u userid:password -H 'Accept: application/vnd.pukkasoft+xml' \
    -d '<?xml version="1.0" encoding="UTF-8"?>XML Data' -X POST http://api.pukkasoft.com/rest/calendars?_method=PUT

ColdFusion Samples

Pukka Software leverages the Adobe ColdFusion. We whipped up a few samples to give you an idea for how to use our first resource, events:

<cfhttp username="user" password="password" url="http://api.pukkasoft.com/rest/calendars" method="get">
	<cfhttpparam type="header" name="Accept" value="application/vnd.pukkasoft+xml" />
</cfhttp>

<-- dump the entire results -->
<cfdump var="#cfhttp#" label="Full Dump" />

<-- list just the event names -->
<cfset x = xmlSearch(xmlParse(cfhttp.FileContent), "/response/events/event/name/") />

<cfloop from="1" to="#arrayLen(x)#" index="ii">
	<cfoutput>#x[ii].xmlText#<br /></cfoutput>
</cfloop>

PHP Samples

Here is a simple example of fetching the events using PHP. You must have the cURL extension compiled in which is common in most builds of PHP. You can check by using phpinfo() which will include details about cURL if it is available. 

<?php
	// create a new cURL resource
	$ch = curl_init();
	
	// set URL and other appropriate options
	curl_setopt($ch, CURLOPT_URL, "http://api.pukkasoft.com/rest/calendars");
	curl_setopt($ch, CURLOPT_HEADER, false);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	
	// set content-type and authorization headers
	$headers = array(
		"Accept: application/vnd.pukkasoft+xml",
	);
	curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
	
	// grab URL and pass it to the browser
	$res = curl_exec($ch);
	
	// a successful request will have http status code 200 for a GET
	if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200)
	{
		// the XML response from the server will be contained in $res
		// You would take this XML and manipulate it to extract the desired data.
		header('Content-type: text/xml; charset=UTF-8');
		echo $res;
	}
	else
	{
		echo 'Error: Status code ' . curl_getinfo($ch, CURLINFO_HTTP_CODE);
	}
	
	// close cURL resource, and free up system resources
	curl_close($ch);
?>

Javascript Samples

Javascript is the language du jour for building interactive applications and mash-ups and we support returning data as JSON and JSONP. We posted some REST consumer examples in our blog and have included one below for creating a per-organization calendar list. This sample uses the popular Javascript library jQuery. 


<html>
<head>
	<title>MotorsportReg.com API Test</title>
	<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
</head>
<body>

<script>
$(document).ready(function()
{
	$.getJSON('http://api.pukkasoft.com/rest/calendars/organization/{your-id-here}.jsonp?jsoncallback=?'
		,{
			dataType: "jsonp"
			,cacheBuster: new Date()
		 }
		,function(json)
		{
			var tbl = '<table>';
			$.each(json.response.events, function(i, evt)
			{
				tbl += '<tr>';
				tbl += '<td><a href="' + evt.detailuri + '">' + evt.name + '</a></td>';
				tbl += '<td>' + evt.type + '</td>';
				tbl += '<td>' + evt.venue.city + ', ' + evt.venue.region + '</td>';
				tbl += '<td>' + evt.start + '</td>';
				tbl += '<td>' + evt.end + '</td>';
				tbl += '<td>' + ((typeof(evt.registration.start) === 'undefined') ? '' : evt.registration.start) + '</td>';
				tbl += '</tr>';
			});

			tbl += '<' + '/table>';
			$('#msrCalendar').append(tbl);
		}
	);
});			

</script>

<div id="msrCalendar"></div>	

</body></html>

IFRAME Sample

In certain cases, it's possible to ask our API to return the results as HTML such that they may be embedded into another site with one line of code. Currently this only works for the per-organization calendar because it does not require authentication but may be expanded in time. Never embed your API key in a public web page or code snippet! 


<iframe src="http://api.pukkasoft.com/rest/calendars/organization/EF396322-CFC3-7452-49FF38E2C1A34BD0.html" height="200" width="100%" style="border: 1px solid #ccc; margin: 10px 0;"></iframe>

RSS/Atom/iCalendar Formats

In certain cases, it's possible to ask our API to return the results as a common format such as RSS, Atom or iCalendar. These feeds are easily digested by many applications because of their ubiquity. This example shows the per-club (unauthenticated) calendar feed for each of the three types. The api.pukkasoft.com feeds are NOT designed for end-user consumption. They may change over time or move locations so we recommend that you retrieve the data, cache it and serve it from your own application. 


http://api.pukkasoft.com/rest/calendars/organization/{your-id-here}.rss  (RSS 2.0)
http://api.pukkasoft.com/rest/calendars/organization/{your-id-here}.atom (Atom 1.0)
http://api.pukkasoft.com/rest/calendars/organization/{your-id-here}.ics  (iCalendar)