server-webapp/src/main/resources/welcome.html - incubator-taverna-server - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Taverna Server %{VERSION}</title>
 </head>
 <body>
 <h1>Taverna Server %{VERSION}</h1>
 <div style="text-align;center">
 	<p>
 		<i>Note that this is a pre-release version. Significant known
 			issues remain open and it is not guaranteed that the service API
 			will be stable.</i>
 	</p>
 </div>
 <p>For a full list of operations, see the <a
     href="%{BASEURL}/services">service listing</a> generated by Apache
 CXF, which indicates where to access the WSDL and WADL descriptions of
 the T2Server interface.</p>
 <p>What follows below is a simple guide to using the server. It does
 <i>not</i> cover all the features; a much more extensive guide is available on
 <a href="http://www.mygrid.org.uk/dev/wiki/display/taverna/Taverna+Server+2.4"
 >the myGrid website</a>.</p>
 <h2>5 Minute Guide to Using the REST API</h2>
 <p>Taverna Server %{VERSION} supports both REST and SOAP APIs; you may use either API
 to access the service and any of the workflow runs hosted by the service. This
 simple guide just discusses the REST API.</p>
 <ol>
   <li>
   <p>The client starts by creating a workflow run. This is done by POSTing a
   T2flow document to the service at the address <tt>%{BASEURL}/rest/runs</tt>
   with the content type <tt>application/vnd.taverna.t2flow+xml</tt>.</p>
   <p>The result of the POST is an <tt>HTTP 201 Created</tt> that gives the
   location of the created run (in a <tt>Location</tt> header),
   <tt>%{BASEURL}/rest/runs/<b>UUID</b></tt> (where <tt><b>UUID</b></tt> is a
   unique string that identifies the particular run; this is also the name of
   the run that you would use in the SOAP interface). Note that the run is not
   yet actually doing anything.</p>
   </li>
   <li>
   <p>Next, you need to set up the inputs to the workflow ports. To set the
   input port, <tt><b>FOO</b></tt>, to have the value <tt><b>BAR</b></tt>, you
   would PUT a message like this to the URI
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/input/input/<b>FOO</b></tt>
   </p>
   <blockquote><pre>&lt;t2sr:runInput xmlns:t2sr=&quot;http://ns.taverna.org.uk/2010/xml/server/rest/&quot;&gt;
     &lt;t2sr:value&gt;<b>BAR</b>&lt;/t2sr:value&gt;
 &lt;/t2sr:runInput&gt;</pre></blockquote>
   </li>
   <li>
   <p>Now you can start the file running. This is done by using a PUT to set
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/status</tt> to the plain text value
   <tt>Operating</tt>.</p>
   </li>
   <li>
   <p>Now you need to poll, waiting for the workflow to finish. To discover the
   state of a run, you can (at any time) do a GET on
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/status</tt>; when the workflow has
   finished executing, this will return <tt>Finished</tt> instead of
   <tt>Operating</tt> (or <tt>Initialized</tt>, the starting state).</p>
   </li>
   <li>
   <p>Every workflow run has an expiry time, after which it will be destroyed
   and all resources (i.e., local files) associated with it cleaned up. By
   default in this release, this is 20 minutes after initial creation. To see
   when a particular run is scheduled to be disposed of, do a GET on
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/expiry</tt>; you may set the time when
   the run is disposed of by PUTting a new time to that same URI. Note that
   this includes not just the time when the workflow is executing, but also
   when the input files are being created beforehand and when the results are
   being downloaded afterwards; you are advised to make your clients regularly
   advance the expiry time while the run is in use.</p>
   </li>
   <li>
   <p>The outputs from the workflow are files created in the <tt>out</tt>
   subdirectory of the run's working directory. The contents of the
   subdirectory can be read by doing a GET on
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out</tt> which will return an XML
   document describing the contents of the directory, with links to each of the
   files within it. Doing a GET on those links will retrieve the actual created
   files (as uninterpreted binary data).</p>
   <p>Thus, if a single output <tt><b>FOO.OUT</b></tt> was produced from the
   workflow, it would be written to the file that can be retrieved from
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out/<b>FOO.OUT</b></tt> and the
   result of the GET on <tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out</tt> would
   look something like this:</p>
   <blockquote><pre>&lt;t2sr:directoryContents xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest"
         xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/"&gt;
     &lt;t2s:file xlink:href="%{BASEURL}/rest/runs/<b>UUID</b>/wd/out/<b>FOO.OUT</b>"
             t2sr:name="<b>FOO.OUT</b>"&gt;out/<b>FOO.OUT</b>&lt;/t2s:file&gt;
 &lt;/t2sr:directoryContents&gt;</pre></blockquote>
   </li>
   <li>
   <p>The standard output and standard error from the T2 Command Line Executor
   subprocess can be read via properties of the special I/O listener. To do
   that, do a GET on
   <tt>%{BASEURL}/rest/runs/<b>UUID</b>/listeners/io/properties/<b>stdout</b></tt>
   (or <tt>.../<b>stderr</b></tt>). Once the subprocess has finished executing,
   the I/O listener will provide a third property containing the exit code of
   the subprocess, called <tt>exitcode</tt>.</p> <p>Note that the supported set
   of listeners and properties will be subject to change in future versions of
   the server, and should not be relied upon.</p>
   </li>
   <li>
   <p>Once you have finished, destroy the run by doing a DELETE on
   <tt>%{BASEURL}/rest/runs/<b>UUID</b></tt>. Once you have done that, none of
   the resources associated with the run (including both input and output
   files) will exist any more. If the run is still executing, this will also
   cause it to be stopped.</p>
   </li>
 </ol>
 <p>All operations described above have equivalents in the
 <a href="%{BASEURL}/soap?wsdl">SOAP service interface</a>.</p>

 <div>
 <hr>
 <p><small>Copyright &copy; 2010&ndash;2014. The University of Manchester.</small></p>
 <p><small>Software Release ID: ${project.version} (commit: ${git.branch})</small></p>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	<title>Taverna Server %{VERSION}</title>
	</head>
	<body>
	<h1>Taverna Server %{VERSION}</h1>
	<div style="text-align;center">
	<p>
	<i>Note that this is a pre-release version. Significant known
	issues remain open and it is not guaranteed that the service API
	will be stable.</i>
	</p>
	</div>
	<p>For a full list of operations, see the <a
	href="%{BASEURL}/services">service listing</a> generated by Apache
	CXF, which indicates where to access the WSDL and WADL descriptions of
	the T2Server interface.</p>
	<p>What follows below is a simple guide to using the server. It does
	<i>not</i> cover all the features; a much more extensive guide is available on
	<a href="http://www.mygrid.org.uk/dev/wiki/display/taverna/Taverna+Server+2.4"
	>the myGrid website</a>.</p>
	<h2>5 Minute Guide to Using the REST API</h2>
	<p>Taverna Server %{VERSION} supports both REST and SOAP APIs; you may use either API
	to access the service and any of the workflow runs hosted by the service. This
	simple guide just discusses the REST API.</p>
	<ol>
	<li>
	<p>The client starts by creating a workflow run. This is done by POSTing a
	T2flow document to the service at the address <tt>%{BASEURL}/rest/runs</tt>
	with the content type <tt>application/vnd.taverna.t2flow+xml</tt>.</p>
	<p>The result of the POST is an <tt>HTTP 201 Created</tt> that gives the
	location of the created run (in a <tt>Location</tt> header),
	<tt>%{BASEURL}/rest/runs/<b>UUID</b></tt> (where <tt><b>UUID</b></tt> is a
	unique string that identifies the particular run; this is also the name of
	the run that you would use in the SOAP interface). Note that the run is not
	yet actually doing anything.</p>
	</li>
	<li>
	<p>Next, you need to set up the inputs to the workflow ports. To set the
	input port, <tt><b>FOO</b></tt>, to have the value <tt><b>BAR</b></tt>, you
	would PUT a message like this to the URI
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/input/input/<b>FOO</b></tt>
	</p>
	<blockquote><pre><t2sr:runInput xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest/">
	<t2sr:value><b>BAR</b></t2sr:value>
	</t2sr:runInput></pre></blockquote>
	</li>
	<li>
	<p>Now you can start the file running. This is done by using a PUT to set
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/status</tt> to the plain text value
	<tt>Operating</tt>.</p>
	</li>
	<li>
	<p>Now you need to poll, waiting for the workflow to finish. To discover the
	state of a run, you can (at any time) do a GET on
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/status</tt>; when the workflow has
	finished executing, this will return <tt>Finished</tt> instead of
	<tt>Operating</tt> (or <tt>Initialized</tt>, the starting state).</p>
	</li>
	<li>
	<p>Every workflow run has an expiry time, after which it will be destroyed
	and all resources (i.e., local files) associated with it cleaned up. By
	default in this release, this is 20 minutes after initial creation. To see
	when a particular run is scheduled to be disposed of, do a GET on
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/expiry</tt>; you may set the time when
	the run is disposed of by PUTting a new time to that same URI. Note that
	this includes not just the time when the workflow is executing, but also
	when the input files are being created beforehand and when the results are
	being downloaded afterwards; you are advised to make your clients regularly
	advance the expiry time while the run is in use.</p>
	</li>
	<li>
	<p>The outputs from the workflow are files created in the <tt>out</tt>
	subdirectory of the run's working directory. The contents of the
	subdirectory can be read by doing a GET on
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out</tt> which will return an XML
	document describing the contents of the directory, with links to each of the
	files within it. Doing a GET on those links will retrieve the actual created
	files (as uninterpreted binary data).</p>
	<p>Thus, if a single output <tt><b>FOO.OUT</b></tt> was produced from the
	workflow, it would be written to the file that can be retrieved from
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out/<b>FOO.OUT</b></tt> and the
	result of the GET on <tt>%{BASEURL}/rest/runs/<b>UUID</b>/wd/out</tt> would
	look something like this:</p>
	<blockquote><pre><t2sr:directoryContents xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest"
	xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/">
	<t2s:file xlink:href="%{BASEURL}/rest/runs/<b>UUID</b>/wd/out/<b>FOO.OUT</b>"
	t2sr:name="<b>FOO.OUT</b>">out/<b>FOO.OUT</b></t2s:file>
	</t2sr:directoryContents></pre></blockquote>
	</li>
	<li>
	<p>The standard output and standard error from the T2 Command Line Executor
	subprocess can be read via properties of the special I/O listener. To do
	that, do a GET on
	<tt>%{BASEURL}/rest/runs/<b>UUID</b>/listeners/io/properties/<b>stdout</b></tt>
	(or <tt>.../<b>stderr</b></tt>). Once the subprocess has finished executing,
	the I/O listener will provide a third property containing the exit code of
	the subprocess, called <tt>exitcode</tt>.</p> <p>Note that the supported set
	of listeners and properties will be subject to change in future versions of
	the server, and should not be relied upon.</p>
	</li>
	<li>
	<p>Once you have finished, destroy the run by doing a DELETE on
	<tt>%{BASEURL}/rest/runs/<b>UUID</b></tt>. Once you have done that, none of
	the resources associated with the run (including both input and output
	files) will exist any more. If the run is still executing, this will also
	cause it to be stopped.</p>
	</li>
	</ol>
	<p>All operations described above have equivalents in the
	<a href="%{BASEURL}/soap?wsdl">SOAP service interface</a>.</p>

	<div>
	<hr>
	<p><small>Copyright © 2010–2014. The University of Manchester.</small></p>
	<p><small>Software Release ID: ${project.version} (commit: ${git.branch})</small></p>
	</div>
	</body>
	</html>