#summary Specification for Taskr's REST API
#labels API,Phase-Design,Phase-Implementation

Taskr provides a [http://en.wikipedia.org/wiki/Representational_State_Transfer RESTful] API for creating and managing tasks. If you're not familiar with the REST concept, a good introduction is available [http://www.xfront.com/REST-Web-Services.html here].

== Client Libraries ==

Although it is possible to talk to the Taskr server through manual HTTP requests, in practice you will probably want to use a REST client library. For example for Ruby, you will probably want to use [ActiveResourceClientExample ActiveResource]; for PHP, one option is the [PHPZendRestClientExample Zend_Rest_Client].

But if you prefer to make HTTP calls directly, read on.

== API Overview ==

Taskr's REST API is built around resources (the only resource currently available being the `task`) and verbs acting on these resources (for `tasks`, the verbs beign `list`, `create`, `view`, and `delete`).

Here is a brief synopsis of the available methods:

|| *Action*                     || *HTTP Method and URL* ||
|| List all tasks               || `GET    /tasks`        ||
|| Create and schedule new task || `POST   /tasks`        ||
|| View task by id              || `GET    /tasks/`*_`id`_*  ||
|| Delete task by id            || `DELETE /tasks/`*_`id`_*  ||

So for example if your Taskr server is running at _http://taskr.example.foo/_, to view the details for the Task with id _123_, you would make a `GET` call over HTTP to the URI `http://taskr.example.foo/tasks/123`.

To delete this Task, you would make a `DELETE` call over HTTP to the same URI. However, since the `DELETE` verb is not widely supported by HTTP clients, you can fake it by using a `POST` call and supplying the parameter `_method=DELETE`. So, you can also delete this task by placing a `POST` call to the URI `http://taskr.example.food/tasks/123?_method=DELETE`.

== `GET /tasks` ==

Lists all tasks currently registered with the server.

|| *Parameter* || *Description ||
|| `format` _(optional)_ || What format the response should be returned in. By default this is HTML. See the _Specifying Output Format_ section below. ||

== `POST /tasks` ==

Creates and schedules a new task for execution.

|| *Parameter* || *Description* ||
|| `name` || A short name for this task. _The task name must be unique!_ ||
|| `schedule_method` || _See below_ ||
|| `schedule_when` || _See below_ ||
|| `action` or `actions` || Specifies the action that should be run when the task is executed. This takes the form of an associative array specifying the type of action to run and parameters for the action. The action type is specified using the `action_class_name`  key and might be something like "Ruby" or "Shell" or "Taskr4rails". The other keys vary, since each action type takes a different set of parameters. See BuiltInActionTypes for more info on various action types, and _see below_ for more information on how to specify multiple actions. ||
|| `format` _(optional)_ || What format the response should be returned in. By default this is HTML. See the _Specifying Output Format_ section below. ||

=== `schedule_method` and `schedule_when` ===

The `schedule_method` and `schedule_when` parameters are used together to specify when and how often your task should be executed.

The `schedule_method` parameter can take one of the following values:

|| *in* || The task will be executed once the given amount of time has passed (i.e. "in 5 minutes") ||
|| *every* || The task will be executed repeatedly (i.e. "every 5 minutes") || 
|| *at* || The task will be executed at the given date and time (i.e. "at 2 AM on December 14, 2008") || 
|| *cron* || The task will be executed according to the given cron schedule. This is an advanced format borrowed from the Linux cron utility. See below for more info. ||

Depending on the value of `schedule_method`, the `schedule_when` parameter specifies a time period, a datetime, or a cron schedule. 

For *in* and *every*, it should be something like "`5s`" for 5 seconds, "`3h`" for 3 hours, "`2d`" for two days. The format is fairly intuitive, but have a look at the [http://openwferu.rubyforge.org/rdoc/classes/OpenWFE/Scheduler.html OpenWFEru Scheduler documentation] if you need details.

For *at* it should be a datetime string. The format is flexible, but its best to stick to a common standard like [http://www.faqs.org/rfcs/rfc2822.html RFC2822]. For example: "`Wed Jan 02 16:53:14 -0500 2008`" or "`2008-01-02 16:53:14`". 

For *cron*, it should be a crontab schedule string; for example to execute the task every minute you would specify "`* * * * *`"; to execute it at 9:30 PM every Monday to Friday it would be "`30 21 * * Mon-Fri`". Try  [http://www.google.ca/search?q=cron+scheduling Googling for more detailed info on the cron syntax]

=== `action` or `actions` ===

As discussed above, the `action` parameter determines the action that will be run when this task is executed at its scheduled time(s). This is given in the form of an associative array. Here are some examples:

Print "Hello World!" to the console:

{{{
'action' => {
  'action_class_name' => "Ruby",
  'code' => "puts 'Hello World!'"
}
}}}

Send an email through a [http://howlr.googlecode.com Howlr] service:

{{{
'action' => {
  'action_class_name' => "Howlr",
  'subject' => "Testing",
  'body' => "Just testing... Please ignore this.",
  'from' => "ebronte@example.foo",
  'recipients' => "mailto:hmiller@example.foo",
}
}}}

It is also possible to assign multiple actions to a task. In that case you should specify `actions` instead of `action` and provide an array of associative arrays as describe above (note that `actions` and `action` are actually interchangeable, so it doesn't matter which you use, but grammatically it makes sense to use the plural when specifying multiple actions). For example, the following will print "Hello!" to the local console and then print "Goodbye!" on a remote Rails server's console (via [Taskr4rails]):

{{{
'actions' => [
  {'action_class_name' => "Ruby",
    'code' => "puts 'Hello!'"},
  {'action_class_name' => "Taskr4rails",
    'url' => "http://rails.example.foo/taskr4rails",
    'auth' => "a4Sik3@s*lsFp!",
    'ruby_code' => "puts 'Goodbye!'"}
]
}}}


== `GET /tasks/`*_`id`_* ==

Retrieves a task currently registered with the server using the task's id.  For example to retrieve the task with id 123, place a `GET` request to http://taskr.example.foo/tasks/123. If the task does not exist, the server will return a response with HTTP code `404` (i.e. `Not Found`).

|| *Parameter* || *Description ||
|| `id` || The ID of the task we want to retrieve. ||
|| `format` _(optional)_ || What format the response should be returned in. By default this is HTML. See the _Specifying Output Format_ section below. ||


== `DELETE /tasks/`*_`id`_* ==

Unschedules and deletes a task using the task's id.  For example to delete the task with id 123, place a `DELETE` request to http://taskr.example.foo/tasks/123. If the task does not exist, the server will return a response with HTTP code `404` (i.e. `Not Found`). If the task is successfully unscheduled and deleted, the server redirects to the task list at `/tasks`.

|| *Parameter* || *Description ||
|| `id` || The ID of the task we want to delete. ||
|| `format` _(optional)_ || What format the response should be returned in. By default this is HTML. See the _Specifying Output Format_ section below. ||


== Specifying Output Format: HTML or XML ==

By default each request will return a response in human-friendly HTML. However, output is availble in XML by attaching `.xml` to the end of the URL (e.g. `http://taskr.example.foo/tasks.xml` or `http://taskr.example.foo/tasks/123.xml`). Alternatively, the format can be specified by providing a `format` parameter in the URL (e.g. `http://taskr.example.foo/tasks?format=xml`).

=== XML Output ===

When output is requested in XML format, Taskr returns task resources serialized into XML. 

Although no official schema currently exists, the format it is fairly straight-forward. In any case, client libraries like [ActiveResourceClientExample ActiveResource] and [PHPZendRestClientExample Zend_Rest_Client] ought to be able to unserialize this data into data objects usable within their respective frameworks.

Here are some examples:

http://taskr.example.foo/tasks/123.xml :
{{{
<?xml version="1.0" encoding="UTF-8"?>
<task>
  <created-by>192.168.2.21</created-by>
  <created-on type="datetime">2007-11-29T15:46:17-05:00</created-on>
  <id type="integer">123</id>
  <last-triggered type="datetime">2007-12-03T10:38:07-05:00</last-triggered>
  <name>Example 1</name>
  <schedule-method>every</schedule-method>
  <schedule-options type="yaml" nil="true"></schedule-options>
  <schedule-when>10m</schedule-when>
  <scheduler-job-id type="integer">0</scheduler-job-id>
  <task-actions type="array">
    <task-action type="Taskr::Models::TaskAction">
      <id type="integer">4</id>
      <action-class-name>Taskr::Actions::Ruby</action-class-name>
      <order type="integer">0</order>
      <task-id type="integer">123</task-id>
      <action-parameters type="array">
        <action-parameter type="Taskr::Models::TaskActionParameter">
          <id type="integer">8</id>
          <name>code</name>
          <value>
            <![CDATA[puts "Hello World!"]]>
          </value>
        </action-parameter>
      </action-parameters>
    </task-action>
  </task-actions>
</task>
}}}

http://taskr.example.foo/tasks.xml :
{{{
<?xml version="1.0" encoding="UTF-8"?>
<tasks type="array">
  <task>
    <created-by>192.168.2.21</created-by>
    <created-on type="datetime">2007-11-29T15:46:17-05:00</created-on>
    <id type="integer">123</id>
    <last-triggered type="datetime">2007-12-03T10:38:07-05:00</last-triggered>
    <name>Example 1</name>
    <schedule-method>every</schedule-method>
    <schedule-options type="yaml" nil="true"></schedule-options>
    <schedule-when>10m</schedule-when>
    <scheduler-job-id type="integer">0</scheduler-job-id>
    <task-actions type="array">
      <task-action type="Taskr::Models::TaskAction">
        <id type="integer">4</id>
        <action-class-name>Taskr::Actions::Ruby</action-class-name>
        <order type="integer">0</order>
        <task-id type="integer">123</task-id>
        <action-parameters type="array">
          <action-parameter type="Taskr::Models::TaskActionParameter">
            <id type="integer">8</id>
            <name>code</name>
            <value>
              <![CDATA[puts "Hello World!"]]>
            </value>
          </action-parameter>
        </action-parameters>
      </task-action>
    </task-actions>
  </task>
  <task>
    <created-by>192.168.2.21</created-by>
    <created-on type="datetime">2007-11-29T15:49:17-05:00</created-on>
    <id type="integer">124</id>
    <last-triggered type="datetime">2007-12-03T10:38:07-05:00</last-triggered>
    <name>Example 2</name>
    <schedule-method>every</schedule-method>
    <schedule-options type="yaml" nil="true"></schedule-options>
    <schedule-when>20m</schedule-when>
    <scheduler-job-id type="integer">0</scheduler-job-id>
    <task-actions type="array">
      <task-action type="Taskr::Models::TaskAction">
        <id type="integer">5</id>
        <action-class-name>Taskr::Actions::Ruby</action-class-name>
        <order type="integer">0</order>
        <task-id type="integer">124</task-id>
        <action-parameters type="array">
          <action-parameter type="Taskr::Models::TaskActionParameter">
            <id type="integer">9</id>
            <name>code</name>
            <value>
              <![CDATA[puts "Goodbye World!"]]>
            </value>
          </action-parameter>
        </action-parameters>
      </task-action>
    </task-actions>
  </task>
</tasks>
}}}