# 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 \
          <%= home_url %>contexts.xml
      >> <?xml version="1.0" encoding="UTF-8"?>
      <contexts>...</contexts>

Getting a single context:

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

Getting the todos within a context:

      $ curl -u username:p4ssw0rd \
      <%= home_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:

- /todos.xml
- /todos/`ID`.xml
- /contexts.xml
- /contexts/`ID`.xml
- /contexts/`ID`/todos.xml
- /projects.xml
- /projects/`ID`.xml
- /projects/`ID`/todos.xml

## 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 \
        -d "project[name]=Build a treehouse for the kids" \
        <%= home_url %>projects.xml -i
    >> HTTP/1.1 201 Created
    Location: <%= home_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 \
        -d "todo[description]=Model treehouse in SketchUp&todo[context_id]=2&todo[project_id]=65" \
        <%= home_url %>todos.xml -i
    >> HTTP/1.1 201 Created
    Location: <%= home_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 -X PUT \
          -d "todo[notes]=use maple texture" \
          <%= home_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 -X PUT \
          <%= home_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 -X DELETE \
          <%= home_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 \
        <%= home_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 = "<%= home_url %>"
    => "<%= home_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:

- `ID`’s in a resource URL indicate that the resource’s unique ID needs to be inserted there
- `...` indicates that unimportant bits of response data have been removed to eliminate noise from the documentation

All examples make use of cURL .