<include TaskForest::REST::PassThrough /head.html />
<include TaskForest::REST::PassThrough /head_docs.html />
<div class="width6 last">
<div class="section_header">The RESTful Web Service Version 1.0</div>
<p>
The <a href="/docs/runningTaskForestd.html"><code>taskforestd</code>
webserver</a> 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.
</p>
<p>
For an introduction to RESTful web services, you can look at
Wikipedia: <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">http://en.wikipedia.org/wiki/Representational_State_Transfer</a>
</p>
<p>
All of the service's URIs for version 1.0 are in
the <code>/rest/1.0/</code> hierarchy. If the service upgrades to a
newer version, 1.0 will be preserved, and the new service will be in,
for example, the <code>/rest/2.0/</code> hierarchy. This way, backward
compatability is preserved while clients migrate to the new interface.
</p>
<p>
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.
</p>
<div class="new_section_header">A Note About URI Notation</div>
<p>
For the purposes of this document we will denote variable parts of
URIs using braces. For example, in the URI
<code>/foo/bar.html/{variable_name}</code> the value of the variable
<code>variable_name</code> will replace the string <code>{variable_name}</code>.
</p>
</div>
<div class="clear_both"></div>
<div class="width2"> </div>
<div class="width10 last">
<div class="new_section_header"><a name="headers_and_footers">Headers and Footers</a></div>
<p>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.</p>
<div class="code"><code><pre>
01 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "<a href="http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd</a>">
02 | <html xmlns="<a href="http://www.w3.org/1999/xhtml"">http://www.w3.org/1999/xhtml"</a>; 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>
</pre></code></div>
<p>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.</p>
<p>Line 04 will display the value of the title for that page. The <code>$</code>
sign is an artifact of the web development framework I'm using.</p>
<p>Lines 08-12 are the main navigation hyperlinks.</p>
<p>Lines 14-24 and 26-40 are the two forms that show up on every page.
These forms allow you to rerun jobs, and mark jobs, respectively.
They're essentially interfaces to the 'rerun' and 'mark' 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. </p>
<p>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.</p>
<div class="code"><code><pre>
</body>
</html></pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_familylist_html">/rest/1.0/familyList.html</a></div>
<div class="code"><code><pre>
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.</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_families_html__family_name_">/rest/1.0/families.html/{family_name}</a></div>
<div class="code"><code><pre>
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</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_joblist_html">/rest/1.0/jobList.html</a></div>
<div class="code"><code><pre>
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.</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_jobs_html__job_name_">/rest/1.0/jobs.html/{job_name}</a></div>
<div class="code"><code><pre>
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</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_status_html">/rest/1.0/status.html</a></div>
<div class="code"><code><pre>
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.</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_logs_htmldate__date_">/rest/1.0/logs.html?date={date}</a></div>
<div class="code"><code><pre>
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.</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_logfile_html__file_">/rest/1.0/logFile.html/{file}</a></div>
<div class="code"><code><pre>
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.</pre></code></div>
<p>
</p>
<div class="new_section_header"><a name="_rest_1_0_request_html">/rest/1.0/request.html</a></div>
<div class="code"><code><pre>
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.
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.</pre></code></div>
<p>
</p>
</div>
<div class="clear_both"></div>
<include TaskForest::REST::PassThrough /foot.html />