REST API Documentation for Developers

Introduction

Tracks is designed to be integrated with scripts, web services, and third-party applications. This page serves as the documentation of our REST API.

Tracks REST API

The Tracks REST API allows developers to integrate Tracks into their applications. It allows applications to access and modify Tracks data, and is implemented as Vanilla XML over HTTP.

The API is a RESTful service. All data is available through the API as a resource to which can be referred using a unique identifier. It responds to a number of the HTTP methods, specifically GET, PUT, POST and UPDATE, and all responses from the API are in a simple XML format encoded as UTF-8.

Authentication

Authentication is handled using Basic HTTP authentication. Your Tracks username and password is used as the authentication credentials for the API. Note that in Basic HTTP authentication, your password is sent in clear text. If you need a more secure authentication solution, you should configure your web server to run Tracks under HTTPS.

Retrieving data from the API

To retrieve data you only need to do an HTTP GET on a resource identifier. For example, if you want to get all the contexts with cURL:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
      <%= root_url %>contexts.xml
  >> <?xml version="1.0" encoding="UTF-8"?>
  <contexts>...</contexts>

Getting a single context:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
      <%= root_url %>contexts/51.xml
  >> <?xml version="1.0" encoding="UTF-8"?>
  <context>...</context>

Getting the todos within a context:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>contexts/51/todos.xml
  >> <?xml version="1.0" encoding="UTF-8"?>
  <todos type="array">...</todos>

You also can apply the pattern shown above with projects instead of contexts.

All data is available according to the following resource paths:

For the todo resources (todos, tickler, done, hidden and calendar) you can limit the returned field to ID, created_at, modified_at, completed_at by adding the parameter limit_fields and setting it to index. For example:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>tickler.xml?limit_fields=index
If you only want to get the active todos, you add the parameter limit_to_active_todos and set it to some value like this: 

  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>todos.xml?limit_to_active_todos=1

Writing to the API

The API provides mechanisms for adding, updating and deleting resources using the HTTP methods PUT, POST and DELETE in combination with the content.

Creating a new project, using curl:


$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    -d "<project><name>Build a treehouse for the kids</name></project>" \
    <%= root_url %>projects.xml -i
>> HTTP/1.1 201 Created
Location: <%= root_url %>projects/65.xml
...

The response is an HTTP/1.1 201 Created with Location header indicating where the new project resource can be found. Now we can add a todo to this project, using curl:


$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    -d "<todo><description>Model treehouse in SketchUp</description><context_id>2</context_id><project_id>65</project_id></todo>" \
    <%= root_url %>todos.xml -i
>> HTTP/1.1 201 Created
Location: <%= root_url %>todos/452.xml
...

The response is a again an HTTP/1.1 201 Created with Location header indicating where the new todo resource can be found. Changing the todo notes, again using curl:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X PUT \
      -d "<todo><notes>use maple texture</notes></todos>" \
      <%= root_url %>todos/452.xml -i
  >> HTTP/1.1 200 OK
  ...

  <?xml version="1.0" encoding="UTF-8"?>
  <todo>
    ...
    <description>Model treehouse in SketchUp</description>

    <notes>use maple texture</notes>
    ...
  </todo>

The response is an HTTP/1.1 200 OK with in the body the XML representation of the updated todo. We provide a shorcut method to toggle a todo done or undone without having to perform the update with the right field values:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X PUT \
      <%= root_url %>todos/452/toggle_check.xml -i
  >> HTTP/1.1 200 OK
  ...

  <?xml version="1.0" encoding="UTF-8"?>
  <todo>
    ...
    <completed-at type=\"datetime\">2007-12-05T06:43:25Z</completed-at>

    <state>completed</state>
    ...
  </todo>

If we want to delete that todo we can call its unique resource identifier (the URL) with the HTTP method DELETE, again with curl:


  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X DELETE \
      <%= root_url %>todos/452.xml -i
  >> HTTP/1.1 200 OK
  ...

The API returns an HTTP/1.1 200 OK and the todo is now deleted.

Dealing with the response and response status

All successful operations respond with a status code of 200 OK or 201 Created depending on the operation. Sometimes a list, say GET /contexts/2/todos.xml will not have any items, it will return an empty list.

The XML for empty list responses look like this, again with curl:


$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    <%= root_url %>contexts/2/todos.xml
>> <?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Consuming the API with ActiveResource

ActiveResource is a thin but powerful wrapper around RESTful services exposed by Ruby on Rails. It will be part of Rails 2.0 but until then you can get it with gem install activeresource --source http://gems.rubyonrails.org --include-dependencies.


$ script/console
Loading development environment (Rails 1.2.4)
>> class Context < ActiveResource::Base; end
=> nil
>> Context.site = "<%= root_url %>"
=> "<%= root_url %>"
>> Context.site.user = "username"
=> "username"

>> Context.site.password = CGI.escape "p4ssw0rd"
=> "p4ssw0rd"
>> Context.find :first
=> #<Context:0x262396c @prefix_options={}, @attributes={...}>
>> >> Context.find :all
=> [#<Context:0x274cfc8 @prefix_options={}, @attributes={...}, ...]

Inspired by 37 Signals ’s Highrise wrapper, we’ve put together a small ruby wrapper (find it in the doc/ directory) for the API which sets up the ActiveResource models for you to play with in an IRB session:


$ SITE="http://username:p4ssw0rd@<%= request.host_with_port %>" irb \
    -r tracks_api_wrapper.rb

irb(main):001:0> inbox = Tracks::Context.find :first
irb(main):002:0> inbox.name
=> "@inbox"
irb(main):003:0>

Notes about the documentation

A few conventions have been applied in the documentation, these are:

All examples make use of cURL .