Deadline API documentation

Overview

The Deadline API is XML over HTTP. Set the following headers to inform Deadline you want to use XML:

Accept: application/xml
Content-Type: application/xml

GET and POST must be used correctly for each method.

Authentication

Basic HTTP authentication is required to access the API. Email address and password are used to authenticate.

Deadline XML fields

A deadline looks like this:


<pre style="overflow: scroll; background-color: #ffc">
<deadline>
<additional-reminder-sent-at type="datetime" nil="true"></additional-reminder-sent-at>
<created-at type="datetime">2008-11-15T11:29:52+00:00</created-at>
<description>Try out the Deadline API</description>
<done type="boolean">false</done>
<due type="datetime">2008-12-12T13:37:00+00:00</due>
<hints type="yaml">---
:includes_time: false

The main fields of interest are:

• id – Use this to refer to the deadline (integer)
• description – A description of the deadline (text)
• due – The date the deadline is due (time with zone)
• done – The done state (boolean)

Time zones

Deadline stores the user’s time zone. Send the API a deadline without a time zone specified and deadline will automatically store it with the user’s time zone.

Scenario: Person interacting with Deadline through a Mac OS widget

• Person wants reminder at 13:37
• Widget sends deadline with due date set to 2008/12/12 13:37
• Deadline saves 13:37 along with the person’s time zone
• Reminder is sent at 13:37 in their time zone

API Methods

Methods return one of:

• An object’s fields in XML
• An object’s errors in XML
• A HTTP status to indicate success or an error

Get a list of deadlines: GET /deadlines


<pre style="overflow: scroll; background-color: #ffc">
curl -X GET -H 'Accept: application/xml' -H 'Content-Type: application/xml' deadlineapp.com/deadlines -u alex@example.com:password
</pre>


Returns deadlines formatted as XML or an empty array.

Search for deadlines: POST /deadlines/search

Note that search requires a POST.


<pre style="overflow: scroll; background-color: #ffc">
curl -X POST -d '' -H 'Accept: application/xml' -H 'Content-Type: application/xml' deadlineapp.com/deadlines/search/?q=shopping -u alex@example.com:test
</pre>


Returns deadlines formatted as XML or an empty array.

Get one deadline

Where 1 is a deadline ID: GET /deadlines/ID


<pre style="overflow: scroll; background-color: #ffc">
curl -X GET -H 'Accept: application/xml' -H 'Content-Type: application/xml' deadlineapp.com/deadlines/1 -u alex@example.com:password
</pre>


Returns a deadline formatted as XML.

Create a Deadline

POST XML to /deadline to create a deadline. The following fields are expected:

• description – English text including a date
• (optional) due – A pre-defined date (skipping Deadline’s parser) in the format YYYY/MM/DD HH:MM


<pre style="overflow: scroll; background-color: #ffc">
curl -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<deadline><description>Try out the Deadline API today</description></deadline>' deadlineapp.com/deadlines -u alex@example.com:password
</pre>


With a pre-defined date:


<pre style="overflow: scroll; background-color: #ffc">
curl -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<deadline><description>Try out the Deadline API</description><due>2008-12-12 13:37</due></deadline>' deadlineapp.com/deadlines -u alex@example.com:password
</pre>


Returns the new deadline’s XML or XML formatted errors.

Update a Deadline

POST to /deadlines/update/ID to update a deadline. You can omit fields that are unchanged.


<pre style="overflow: scroll; background-color: #ffc">
curl -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<deadline><description>Different text</description></deadline>' deadlineapp.com/deadlines/update/1 -u alex@example.com:password
</pre>


Returns an OK header or XML formatted errors.

Delay or make as done

GET /deadlines/delay/ID to delay a deadline by the default delay period.


<pre style="overflow: scroll; background-color: #ffc">
curl -X GET -H 'Accept: application/xml' -H 'Content-Type: application/xml' deadlineapp.com/deadlines/delay/1 -u alex@example.com:test
</pre>


This returns the same results as update.

To toggle the done state, update a deadline with:


<pre style="overflow: scroll; background-color: #ffc">
<done>true</done>
</pre>



<pre style="overflow: scroll; background-color: #ffc">
<done>false</done>
</pre>


Delete a Deadline

Perform a GET request to /deadlines/destroy/ID to delete a deadline.


<pre style="overflow: scroll; background-color: #ffc">
curl -X GET -H 'Accept: application/xml' -H 'Content-Type: application/xml' deadlineapp.com/deadlines/destroy/1 -u alex@example.com:password
</pre>