The RESTful Web Service Version 1.0

The taskforestd webserver hosts one or more RESTful Web Services. The web service allows you to write, in any programming language, your own client software that integrates with TaskForest.

For an introduction to RESTful web services, you can look at Wikipedia: http://en.wikipedia.org/wiki/Representational_State_Transfer

All of the service's URIs for version 1.0 are in the /rest/1.0/ hierarchy. If the service upgrades to a newer version, 1.0 will be preserved, and the new service will be in, for example, the /rest/2.0/ hierarchy. This way, backward compatability is preserved while clients migrate to the new interface.

The documentation that follows describes the common 'header' and 'footer' XHTML. This is followed by a list of all the URIs and families of URIs supported by the web service, the HTTP methods that each URI supports, and a description of the service for the client software developer.

A Note About URI Notation

For the purposes of this document we will denote variable parts of URIs using braces. For example, in the URI /foo/bar.html/{variable_name} the value of the variable variable_name will replace the string {variable_name}.

 

Every page with an HTTP Status code of 200-207 served by version 1.0 of the web service will start with the html shown below.


01 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
02 | <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
03 |  <head>
04 |   <title>$title</title>
05 |  </head>
06 |  <body>
07 |
08 |    <div class="header_navigation">
09 |      <a href="/rest/1.0/familyList.html">Family List</a>
10 |      <a href="/rest/1.0/jobList.html">Job List</a>
11 |      <a href="/rest/1.0/status.html">Status</a>
12 |    </div>
13 |
14 |    <form id="rerun" class="request" method="POST" action="/rest/1.0/request.html">
15 |      <label for="rerun_family">Family</label><input id="rerun_family" name="family" /><br />
16 |      <label for="rerun_job">Job</label><input id="rerun_job" name="job" /><br />
17 |      <label for="rerun_log_date">Log Date</label><input id="rerun_log_date" name="log_date" /><br />
18 |      <label for="rerun_options">Options</label><select id="rerun_options" name="options">
19 |        <option value="">None</option>
20 |        <option value="cascade">Cascade</option>
21 |        <option value="dependents_only">Dependents Only</option>
22 |      </select>
23 |      <input type=submit name=submit  value="Rerun"/>
24 |    </form>
25 |
26 |    <form id="mark" class="request" method="POST" action="/rest/1.0/request.html">
27 |      <label for="mark_family">Family</label><input id="mark_family" name="family" /><br />
28 |      <label for="mark_job">Job</label><input id="mark_job" name="job" /><br />
29 |      <label for="mark_log_date">Log Date</label><input id="mark_log_date" name="log_date" /><br />
30 |      <label for="mark_options">Options</label><select id="mark_options" name="options">
31 |        <option value="">None</option>
32 |        <option value="cascade">Cascade</option>
33 |        <option value="dependents_only">Dependents Only</option>
34 |      </select>
35 |      <label for="mark_status">Status</label><select id="mark_status" name="status">
36 |        <option value="Success">Success</option>
37 |        <option value="Failure">Failure</option>
38 |      </select>
39 |      <input type=submit name=submit  value="Mark"/>
40 |    </form>
41 |
42 |    <form id="logs" class="request" method="GET" action="/rest/1.0/logs.html">
43 |      <label for="logs_date">Date</label><input id="logs_date" name="date" size=8 maxlength=8/><br />
44 |      <input type=submit name=submit  value="View Logs"/>
45 |    </form>
46 |
47 |    <form id="release" class="request" method="POST" action="/rest/1.0/request.html">
48 |      <label for="release_family">Family</label><input id="release_family" name="family" /><br />
49 |      <label for="release_job">Job</label><input id="release_job" name="job" /><br />
50 |      <label for="release_log_date">Log Date</label><input id="release_log_date" name="log_date" /><br />
51 |      <input type=submit name=submit  value="Release"/>
52 |    </form>
53 |
54 |    <form id="hold" class="request" method="POST" action="/rest/1.0/request.html">
55 |      <label for="hold_family">Family</label><input id="hold_family" name="family" /><br />
56 |      <label for="hold_job">Job</label><input id="hold_job" name="job" /><br />
57 |      <label for="hold_log_date">Log Date</label><input id="hold_log_date" name="log_date" /><br />
58 |      <input type=submit name=submit  value="Hold"/>
59 |    </form>
60 |
61 |    <form id="hold" class="request" method="POST" action="/rest/1.0/request.html">
62 |      <label for="release_hold_family">Family</label><input id="release_hold_family" name="family" /><br />
63 |      <label for="release_hold_job">Job</label><input id="release_hold_job" name="job" /><br />
64 |      <label for="release_hold_log_date">Log Date</label><input id="release_hold_log_date" name="log_date" /><br />
65 |      <input type=submit name=submit  value="Release Hold"/>
66 |    </form>
    

Lines 01-02 describe the file as an XHTML file. I chose XHTML because the output can be viewed by any web browser. If you would like another format, drop me an email.

Line 04 will display the value of the title for that page. The $ sign is an artifact of the web development framework I'm using.

Lines 08-12 are the main navigation hyperlinks.

Lines 14-66 are the six forms that show up on every page. These forms allow you to rerun jobs, mark jobs, view logs, release jobs, hold jobs and release holds, respectively. They're essentially interfaces to the 'rerun' and 'mark', 'status', 'release', 'hold' and 'releaseHold' commands. The log_date form variable is a date formatted like YYYYMMDD and is used to determine which day's job should be rerun. If left blank, the system uses today's date.

Every page with an HTTP Status code of 200-207 served by version 1.0 of the web service will end with the html shown below.

  </body>
 </html>

 HEAD
 ====
       This URI does not support this method.

 GET
 ===
       DESCRIPTION
       ...........
       Use this URI to retrieve a list of all Families.  These are all the
       files in the directory specified by the family_dir option in the
       taskforestd configuration file.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The client should not send any content to this URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <ul class=family_list>
       02 |     <li class=family_name><a href="/rest/1.0/families.html/$file_name">$file_name</a></li>
       03 | </ul>

       Line 02 will appear 0 or more times, depending on how many Families
       are present.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       This URI does not support this method.

 HEAD
 ====
       DESCRIPTION
       ...........
       Send this URI the HEAD method to see if the family specified within
       the URI has changed recently.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The family name is represented by {family_name} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       The HTTP content is empty.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 GET
 ===
       DESCRIPTION
       ...........
       Send this URI the GET method to retrieve the contents of the family
       file whose name is specified within the URI.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The family name is represented by {family_name} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <div class="family_title">Viewing family $file_name</div>
       02 | <div id="family_contents_div" class="file_contents"><pre>$file_contents</pre></div>
       03 | <form name="family_form" action="/rest/1.0/families.html/$file_name" method="POST">
       04 |   <input type=hidden name="_method" value="PUT">
       05 |   <textarea name="file_contents" rows=20 cols=100>$file_contents</textarea>
       06 |   <br>
       07 |   <input type=submit value="Update Family" name=update />
       08 | </form>

       Line 01 displays the family name.  Line 02 displays the
       contents of the family file in its own div.  Line 03-08 are a
       form that can be used to update the family file.  Note here
       that the method is POST, but there is a form variable called
       "_method" whose value is "PUT".  This is a common idiom in
       RESTful service development because most web browsers only
       support GET and POST.  This is called overloaded POST.

       With the taskforestd web service, whenever you need to use the
       HEAD, PUT or DELETE methods, you can use POST and define the
       'real' method with the _method form variable.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 PUT
 ===
       DESCRIPTION
       ...........
       Send this URI the PUT method to create a new family file or to
       change the contents of an existing family file.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       If your client is really using the PUT method, the contents of
       the family file should be sent in the contents of the HTTP
       request.

       If, however, your client is using overloaded POST, then the
       content that you would have sent with the PUT must be in the
       file_contents form variable.  Overloaded POST is explained in
       the description of the GET method, above.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In the typical case, after creating the new family file, or
       changing the contents of the existing family file, the server will
       return the  same contents as in the case of the GET method.

       HTTP STATUS CODES
       .................
       200 - OK
       400 - The file_contents form variable was missing, in the case of
             Overloaded POST
       500 - The file could not be written - likely a permission issue

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       DESCRIPTION
       ...........
       Send this URI the DELETE method to delete the family file named in
       the URI.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The family name is represented by {family_name} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In the case of DELETE, the server will never return any content.

       HTTP STATUS CODES
       .................
       204 - Delete was successful and the client should not expect any
             content
       500 - The file could not be deleted - likely a permission issue

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Content-Length
       o Content-Type

 HEAD
 ====
       This URI does not support this method.

 GET
 ===
       DESCRIPTION
       ...........
       Use this URI to retrieve a list of all Jobs.  These are all the
       files in the directory specified by the job_dir option in the
       taskforestd configuration file.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The client should not send any content to this URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <ul class=job_list>
       02 |     <li class=job_name><a href="/rest/1.0/jobs.html/$file_name">$file_name</a></li>
       03 | </ul>

       Line 02 will appear 0 or more times, depending on how many Jobs
       are present.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       This URI does not support this method.

 HEAD
 ====
       DESCRIPTION
       ...........
       Send this URI the HEAD method to see if the job specified within
       the URI has changed recently.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The job name is represented by {job_name} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       The HTTP content is empty.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 GET
 ===
       DESCRIPTION
       ...........
       Send this URI the GET method to retrieve the contents of the job
       file whose name is specified within the URI.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The job name is represented by {job_name} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <div class="job_title">Viewing job $file_name</div>
       02 | <div id="job_contents_div" class="file_contents"><pre>$file_contents</pre></div>
       03 | <form name="job_form" action="/rest/1.0/jobs.html/$file_name" method="POST">
       04 |   <input type=hidden name="_method" value="PUT">
       05 |   <textarea name="file_contents" rows=20 cols=100>$file_contents</textarea>
       06 |   <br>
       07 |   <input type=submit value="Update Job" name=update />
       08 | </form>

       Line 01 displays the job name.  Line 02 displays the contents of
       the job file in its own div.  Line 03-08 are a form that can be
       used to update the job file.  Note here that the method is POST,
       but there is a form variable called "_method" whose value is "PUT".
       This is a common idiom in RESTful service development because most
       web browsers only support GET and POST.  This is called overloaded
       POST.

       With the taskforestd web service, whenever you need to use the
       HEAD, PUT or DELETE methods, you can use POST and define the 'real'
       method with the _method form variable.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 PUT
 ===
       DESCRIPTION
       ...........
       Send this URI the PUT method to create a new job file or to
       change the contents of an existing job file.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       If your client is really using the PUT method, the contents of the
       job file should be sent in the contents of the HTTP request.

       If, however, your client is using overloaded POST, then the content
       that you would have sent with the PUT must be in the file_contents
       form variable.  Overloaded POST is explained in the description of
       the GET method, above.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In the typical case, after creating the new job file, or changing
       the contents of the existing job file, the server will return the
       same contents as in the case of the GET method.

       HTTP STATUS CODES
       .................
       200 - OK
       400 - The file_contents form variable was missing, in the case of
             Overloaded POST
       500 - The file could not be written - likely a permission issue

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       DESCRIPTION
       ...........
       Send this URI the DELETE method to delete the job file named in the
       URI.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The job name is represented by {job_name} and is part of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In the case of DELETE, the server will never return any content.

       HTTP STATUS CODES
       .................
       204 - Delete was successful and the client should not expect any
             content
       500 - The file could not be deleted - likely a permission issue

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Content-Length
       o Content-Type

 HEAD
 ====
       This URI does not support this method.

 GET
 ===
       DESCRIPTION
       ...........
       Send this URI the GET method to get the status of today's jobs.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       None - no additional information is needed.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <div class=status>
       02 |     <dl class=job>
       03 |       <dt>Family Name</dt>
       04 |       <dd><a href="/rest/1.0/families.html/$family_name">$family_name</a></dd>
       05 |       <dt>Job Name</dt>
       06 |       <dd><a href="/rest/1.0/jobs.html/$base_name">$name</a></dd>
       07 |       <dt>Status</dt>
       08 |       <dd>$status</dd>
       09 |       <dt>Return Code</dt>
       10 |       <dd>$rc</dd>
       11 |       <dt>Time Zone</dt>
       12 |       <dd>$tz</dd>
       13 |       <dt>Scheduled Start Time</dt>
       14 |       <dd>$start</dd>
       15 |       <dt>Actual Start Time</dt>
       16 |       <dd>$actual_start</dd>
       17 |       <dt>Stop Time</dt>
       18 |       <dd>$stop</dd>
       19 |     </dl>
       20 | </div>

       Lines 02-19 will appear 0 or more times, once for every job that
       appears in the output of the status command.  The --collapse option
       is implied in the web service; pending repeat jobs are not
       displayed.

       If the job has an associated log file (in other words: if the
       wrapper script that ran it was run_with_log, and the status is
       either Running, Success or Failure) then line 08 will look like
       this:

       08 |       <dd><a href="/logFile.html/$output_file">$status</a></dd>

       HTTP STATUS CODES
       .................
       200 - OK

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Content-Length
       o Content-Type

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       This URI does not support this method.

 HEAD
 ====
       This URI does not support this method.

 GET
 ===
       DESCRIPTION
       ...........
       Send this URI the GET method to browse the log directory for a
       particular date - to see which jobs ran on that day, and when, and
       what the exit codes were.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The date is specified as a query parameter.  The date must be in
       the YYYYMMDD format.  If the date is omitted, then the date will
       default to the current date, and jobs with a status of 'Ready' or
       'Waiting' will also be displayed.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | <div class=status>
       02 |     <dl class=job>
       03 |       <dt>Family Name</dt>
       04 |       <dd><a href="/rest/1.0/families.html/$family_name">$family_name</a></dd>
       05 |       <dt>Job Name</dt>
       06 |       <dd><a href="/rest/1.0/jobs.html/$base_name">$name</a></dd>
       07 |       <dt>Status</dt>
       08 |       <dd>$status</dd>
       09 |       <dt>Return Code</dt>
       10 |       <dd>$rc</dd>
       11 |       <dt>Time Zone</dt>
       12 |       <dd>$tz</dd>
       13 |       <dt>Actual Start Time</dt>
       14 |       <dd>$actual_start_dt</dd>
       15 |       <dt>Stop Time</dt>
       16 |       <dd>$stop_dt</dd>
       17 |     </dl>
       18 | </div>

       Lines 02-17 will appear 0 or more times, once for every job that
       appears in the output of the status command.

       If the job has an associated log file (in other words: if the
       wrapper script that ran it was run_with_log, and the status is
       either Running, Success or Failure) then line 08 will look like
       this:

       08 |       <dd><a href="/logFile.html/$output_file">$status</a></dd>

       HTTP STATUS CODES
       .................
       200 - OK

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Content-Length
       o Content-Type

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       This URI does not support this method.

 HEAD
 ====
       DESCRIPTION
       ...........
       Send this URI the HEAD method to see if the log file specified
       within the URI has changed recently.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The name of the log file is represented by {file} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       The HTTP content is empty.

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 GET
 ===
       DESCRIPTION
       ...........
       Send this URI the HEAD method to browse the log file specified
       within the URI.

       Send this URI the GET method to browse the log directory for a
       particular date - to see which jobs ran on that day, and when, and
       what the exit codes were.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       The name of the log file is represented by {file} and is part
       of the URI.

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In a typical case, the server will send the header and footer,
       and the 'real' content in between.  The content will look like
       this:

       01 | <div class="title">Viewing log file $file_name</div>
       02 |
       03 | <div id="file_contents_div" class="file_contents"><pre>$file_contents</pre></div>

       HTTP STATUS CODES
       .................
       200 - Everything's OK
       304 - The resource has not been modified since the time
             specified in the request If-Modified-Since header,
             OR
             The calculated Etag of the resource is the same as that
             specified in the request If-None-Match header.
       404 - The resource was not found

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Last-Modified
       o ETag
       o Content-Length
       o Content-Type

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       This URI does not support this method.

 DELETE
 ======
       This URI does not support this method.

 HEAD
 ====
       This URI does not support this method.

 GET
 ===
       This URI does not support this method.

 PUT
 ===
       This URI does not support this method.

 POST
 ====
       DESCRIPTION
       ...........
       Send a POST to this URI to request a job be marked as success or
       failure, or be rerun.

       REPRESENTATION SENT BY CLIENT TO SERVER
       .......................................
       There are three required form variables: "family", "job", and
       "submit".  The first is the name of the family, and the second is
       the name of the job.  If the value of the "submit" variable is
       "Rerun", then that job is rerun.  If the value is "Mark", then the
       job will be marked based on the value of the form variable
       "status", which can take a value of "Success" or "Failure".

       In either case, mark or rerun, the optional variable "options" is
       also permitted.  If it has a value, its value can be either
       "cascade" or "dependents_only".  These are treated the same way as
       the command line options to the 'rerun' and 'mark' commands.

       Other values for the "submit" variable are "View Logs", "Release",
       "Hold" and "Release Hold".  For details on the fields they can 
       accept, please see their respective pages and the forms in the
       Headers above. 

       REPRESENTATION SENT BY SERVER TO CLIENT
       .......................................
       In every case, the server will send the header and footer, and
       the 'real' content in between.  The content will look like this:

       01 | Request accepted.

       HTTP STATUS CODES
       .................
       200 - OK
       500 - The request could not be honored.

       HTTP RESPONSE HEADERS
       .....................
       o Date
       o Content-Length
       o Content-Type

 DELETE
 ======
       This URI does not support this method.