Skip to end of metadata
Go to start of metadata

Decay service

For my inspiration, also see the draft for documenting the REST API of Remote Execution Service

Main resources

  • User
  • Workflow (is-a Monitorable)
  • Activity (is-a Monitorable)
  • Monitor
  • HealthReport
  • Status

A User has a collection of Workflows, and a collection of Monitors.

A Workflow for now is simply a Scufl file as produced by Taverna 1. Internally the t2 translator will provide the t2 activities. We might get a T2Workflow seralisation later, so maybe we should even just call it ScuflWorkflow for now, as t1 workflows are serialised as Scufl.

A Monitor is a "job" of what is to be tested when and how. A Monitor has one Monitoriable or something (most of the time the instance Workflow) and 0 or more HealthReports. (ie. reports of testing that workflow). A Monitor has a Status, which is basically the result of the latest HealthReport.

A HealthReport describes how a test (a monitoring) ended up, possibly saying which Activities caused it to fail.

A Workflow (when translated and so on) has 0 or more Activities.

An Activity is basically an invokable service as described by t2, for instance a WSDL activity. We might not need to expose these in the first iterations, but they are the targets of error reports in a HealthReport.

Suggested URL layout

(Note that you have to escape {brackets} in this wiki (sad) ) 

URL template

Resource

/

Capabilities


/user;current

Current user (Redirects to /users/{user} based on auth info)

/user/{user}

User

/user/{user}/workflows

Collection of Workflows

/user/{user}
/workflow/{workflow}

Workflow (Scufl file)

/user/{user}/workflow/{workflow}/activities

Collection of Activities

/user/{user}/monitors

Collection of Monitors

/user/{user}/monitor/{monitor}

Monitor

/user/{user}/monitor/{monitor}/reports

Collection of HealthReports

/user/{user}/monitor/{monitor}/report/{report}

HealthReport

/user/{user}/monitor/{monitor}/status

Status

/activities

Collection of all known Activities (hidden for unprivileged users)

/activity/{activity}

Activity

We can discuss with the REST bloggers if it's reasonable to separate between plural and singular as in /workflows and /workflow/ or just go for either /workflows or /workflows all the time. I'm not so sure of this duality proposed by myself here..

Example of usage and representation documents

Getting started: The capabilities document

GET / HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.omii.tam+xml

<capabilities xmlns="http://www.omii.ac.uk/2008/tam">
  <currentUser xlink:href="/user;current"          />
  <activities xlink:href="/activities"          />
</capabilities>

This is the starting point for the REST client, the Capabilities document. Here they will find the links on where to go next, using the "hypermedia as the engine of the application state". Everything else is just based on understanding the resource representations (ie. the XML in this example), following its links and using the 4 basic CRUD operations of HTTP: POST (create), GET (read), PUT (update), DELETE (delete).

In this example we only need the current user and the list of all activities. (The last one will only be accessible for admin users).

The user document 

We can then follow the link to find the User document:

GET /user;current HTTP/1.1
Authorization: alksd9=lsjkd


HTTP/1.1 307 Temporary redirect
Location: http://blah.com/user/fish

GET /user/fish HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.omii.tam+xml

<user xmlns="http://www.omii.ac.uk/2008/tam">
   <workflows xlink:href="/user/fish/workflows"      />
   <monitors xlink:href="/user/fish/monitors"      />
</user>

From here we would know where to POST our workflow that we want to monitor:

Uploading a workflow

POST /user/fish/workflows HTTP/1.1
Content-Type: application/vnd.taverna.scufl+xml
<?xml version="1.0" encoding="UTF-8"?>
<s:scufl xmlns:s="http://org.embl.ebi.escience/xscufl/0.1alpha" version="0.2" log="0">
  <s:workflowdescription
     (...)
</s:scufl>

HTTP/1.1 201 Created
Location: http://blah.com/user/fish/workflow/69D54A6B-60E4-4404-B3C3-7A018DBF66CE

We can confirm if we want:

GET  /user/fish/workflow/69D54A6B-60E4-4404-B3C3-7A018DBF66CE HTTP/1.1
Accept: application/vnd.taverna.scufl+xml

HTTP/1.1 200 OK
Content-Type:  application/vnd.taverna.scufl+xml

<?xml version="1.0" encoding="UTF-8"?>
<s:scufl xmlns:s="http://org.embl.ebi.escience/xscufl/0.1alpha" version="0.2" log="0">
  <s:workflowdescription       (...)
</s:scufl>

Note that the server for abuse reasons should not accept non-scufls. (Could test that the workflow is translatable)

If we ask without specifying the Taverna SCUFL content type we can get a list of what the service knows about this workflow:

 Following <activities> would give a list of all the activities recognised in this workflow. Following <monitors> would give a list of all the monitors (this user has access to) that tests this workflow.

Adding and retrieving a monitor

We'll post a little Monitor document that describes as a minimum what we want to monitor, and let the server deside the rest according to his defaults:

POST /user/fish/monitors HTTP/1.1
Content-Type: application/vnd.omii.tam+xml

<monitor xmlns="http://www.omii.ac.uk/2008/tam">
   <monitorable xlink:href="http://blah.com/user/fish/workflow/69D54A6B-60E4-4404-B3C3-7A018DBF66CE"      >
</monitor>

HTTP/1.1 201 Created
Location: http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1

It might even be allowed to use a xlink:href to a publicly visible Scufl on myExperiment, avoiding the upload to /workflows. (This upload could still be done under the hood if needed by the server).

The Location header gives the URI for the newly created monitor. If we retrieve the Monitor document we can see the defaults provided by the server, in addition to links to more information about the monitor:

GET /user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.omii.tam+xml

<monitor xmlns="http://www.omii.ac.uk/2008/tam">
   <monitorable xlink:href="http://blah.com/user/fish/workflow/69D54A6B-60E4-4404-B3C3-7A018DBF66CE"    >
   <updateInterval>PT5M<!-- Every 5th minute --></updateInterval>
   <reports xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports"    />
   <status xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/status"     />
</monitor>

We could update the interval to every 15th minute by modifying this document and PUT-ing it back. We're also giving it a dc:title now:

 PUT /user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1 HTTP/1.1
 Content-Type: application/vnd.omii.tam+xml

<monitor xmlns="http://www.omii.ac.uk/2008/tam">
   <dc:title>Check blast workflow</dc:title>
   <monitorable xlink:href="http://blah.com/user/fish/workflow/69D54A6B-60E4-4404-B3C3-7A018DBF66CE"    >
   <updateInterval>PT15M<!-- Every 15th minute --></updateInterval>
   <reports xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports"   />
   <status xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/status"     />
</monitor>

HTTP/1.1 204 No content

Notice that such a PUT should not be allowed to change generated links such as <reports> and <status>, so any value here can just be ignored, or if being strict, reported as 403 Forbidden.

If we now get the user's Monitor collection we should also see the previously created monitor, including our updated title:

Checking reports

GET /user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports HTTP/1.1

HTTP/1.1 200 OK
Content-Type:  application/vnd.omii.tam+xml

<reports xmlns="http://www.omii.ac.uk/2008/tam">
  <monitor xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1"  />
  <feed xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports.atom"    />

  <report xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T123305Z"    dc:created="20080215T123305Z" />
  <report xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T113145Z"    dc:created="20080215T113145Z" />
  <report xlink:href="/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080214T234304Z"    dc:created="20080214T234304Z" />

</reports>

The list of reports could grow big, so perhaps some kind of date limiting or number limiting is needed..

We could also check this as an Atom feed, which URL we can find by content negotiation or by following the <feed> tag:

GET /user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports.atom HTTP/1.1
Accept: application/atom+xml


HTTP/1.1 200 OK
Content-Type: application/atom+xml

<feed xmlns="http://www.w3.org/2005/Atom">

 <title>Reports for monitor 'Check blast workflow'</title>
 <link href="http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports.atom"    rel="self"/>
 <link href="http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports"   />
 <updated>2007-02-16T18:30:02Z</updated>
 <id>http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/reports</id>

 <entry>
   <title>Failed monitoring at 2008-02-15 12:33:05</title>
   <link href="http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T123305Z"   />
   <id>http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T123305Z</id>
   <updated>2008-02-15T12:33:05Z</updated>
   <summary>1 activity failed</summary>
 </entry>

  <entry>
   <title>Successful monitoring at 2008-02-15 11:31:45Z</title>
   <link href="http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T113145Z"   />
   <id>http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080215T113145Z</id>
   <updated>2008-02-15T11:31:45Z</updated>
   <summary>0 activities failed</summary>
 </entry>
 <entry>
   <title>Failed monitoring at 2008-02-14 23:43:04Z</title>
   <link href="http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080214T234304Z"   />
   <id>http://blah.com/user/fish/monitor/C3F32A5B-2754-48F6-B242-114967C4DAA1/report/20080214T234304Z</id>
   <updated>2008-02-14T23:43:04Z</updated>
   <summary>2 activities failed</summary>
 </entry>


</feed>

Let's have a look at an actual report:

Status

The status can give information about the current state of the workflow/activity.

The reliability could be calculated by the latest monitor reports, and could for instance be used by a t2 plugin that chooses between activities at runtime execution of a workflow. Notice the use of Dublin core for saying when the status was last updated (ie. when the last report was produced).

Activities

I'm not mentioning now how to add activities manually, or how to specify them. Currently we can say that they are only created from a Scufl workflow.

However, we might get a report that says that a particular activity has failed, and want to explore more about that activity. Some of this information could be extracted from t2.

Similary as in <workflow> following <workflows> would give a list of workflows using the activity, and <monitors> list monitors that test this activity (directly?).

Labels
  • None