TaskrAPI - ruby-taskr - Specification for Taskr's REST API

Updated Jan 02, 2008 by matt.zukowski
Labels:	API, Phase-Design, Phase-Implementation

TaskrAPI

Specification for Taskr's REST API

Taskr provides a RESTful API for creating and managing tasks. If you're not familiar with the REST concept, a good introduction is available 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 ActiveResource; for PHP, one option is the 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 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 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 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 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 ActiveResource and 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>