screeningBee Data Analysis Tools

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Testing the REST Interface ======

Examples for testing the REST Interface on the development server:

Checkout the example workflows from Subversion:
<code>
cd ~/stage/bee/
svn co svn://svn.code.sf.net/p/screeningbee/code/trunk/project screeningbee-project
</code>

Check the status of the queue before submission:
<code>
qstat
</code>

Start a new workflow:
<code>
cd ~/stage/bee/screeningbee-project/test/mockdata/workflows/
/usr/bin/curl --request POST --data-urlencode workflow@VacciniaShdCrrVer010bGENERALCH3R2011b.xml http://localhost:12345/apiv1/processes
</code>

Check running workflows:
<code>
/usr/bin/curl http://localhost:12345/apiv1/processes
</code>


======Using the REST interface======

======API Version 1======
The basic principles of the API are described in the [REST Interface Design-/display/bee/REST+interface+design] document.
These resources are accessible under the /apiv1/ prefix.

======Processes======
The /apiv1/processes REST resource provides interface to query, create and manage processes.
The following methods are available:

====GET apiv1/processes====
Get method on  all submitted processes. It doesn’t have any parameters.

**Response:**

The response of this method is a JSON encoded [WorkflowDTO-http://svn.code.sf.net/p/screeningbee/code/trunk/bee-commons/src/main/java/ch/systemsx/bee/workflowmanager/rest/dto/WorkflowDTO.java object, which contains the status of the processes, in case of HTTP status code 200. Otherwise the response is an error message.

**Examples**:
  -  ''wget http://localhost:9999/apiv1/processes'' - gives the status of the submitted processes.

====GET apiv1/processes/PROCESS_ID====
Get method on specific process (identified by PROCESS_ID). It doesn’t have any parameters.

**Response:**

The response of this method is a JSON encoded [WorkflowDTO-http://svn.code.sf.net/p/screeningbee/code/trunk/bee-commons/src/main/java/ch/systemsx/bee/workflowmanager/rest/dto/WorkflowDTO.java object, which contains the status of the process, in case of HTTP status code 200. Otherwise the response is an error message.

**Examples**:
  -  ''wget http://localhost:9999/apiv1/processes/123'' - gives the status of the process 123.

====GET apiv1/processes/countRunningProcesses====
The get method on this resource queries how many processes are currently running.

**Response**:

The response of this method is a message with the count of processes currently running, in case of HTTP status code 200. Otherwise the response is an error message.

**Examples**:
  -  ''wget http://localhost:12345/apiv1/processes/countRunningProcesses'' - returns how many processes are running.


====POST /apiv1/processes====
The POST method on this resource creates and starts a new process.
The new started process will run the workflow submitted with the XML file parameter and, optionally, with the variable values submitted.

**POST Parameters:**

__Submit workflow description__\\
Two possibilities:\\
**(1)** Specify the path to the XML file containing the description of the workflow to submit.\\
The file must be supplied with the option ''--data-urlencode'' followed with the parameter name ''workflow'' and an ''@''. That will tell ''curl'' to read the content of this file and assign it as value of the paramater name ''workflow''.\\
**(2)** Specify the storage provider dataset ID of the worklfow description file (only possible if it is stored as a dataset in the used storage provider).\\
The dataset ID must be supplied with the option ''--data-urlencode'' followed with the parameter name ''workflow.id'', the ''='' and the ID of the workfow to submit.


__Submit workflow variables__\\
Optionally, one or several variable names and its values for substitution in the ''workflow.xml'', can be also supplied with the ''--data-urlencode'' option. When using the ''--data-urlencode'' option more than once on the same  command  line, ''curl'' will merge them together with a separating  ''&'' symbol.

**Response:**

In case of HTTP status code 200, the response is the ID of the new created process. Otherwise the response is an error message.

**Examples**:
<code>curl -X POST --data-urlencode workflow@src/test/resources/functional/workflows/MultipleModules_vars_val.xml http://localhost:9999/apiv1/processes</code>
Creates a new process with the submitted workflow description file and puts it in the execution queue. It returns de ID of the newly created process.

<code>curl -X POST --data-urlencode workflow@src/test/resources/functional/workflows/MultipleModules_vars_val.xml --data-urlencode "RawImages=0bCDME-BE02" http://localhost:9999/apiv1/processes</code>
Creates a new process with the submitted workflow description file and puts it in the execution queue. The workflow description file will be searched for the variable ''${RawImages}'' and every hit will be substituted by the value ''0bCDME-BE02''. It returns de ID of the newly created process.

<code>curl -X POST --data-urlencode "workflow.id=20130620095251781-41392" --data-urlencode "RawImages=0bCDME-BE02" http://localhost:9999/apiv1/processes</code>
Creates a new process with the content of the dataset with the submitted ID, and puts it in the execution queue. The workflow description file will be searched for the variable ''${RawImages}'' and every hit will be substituted by the value ''0bCDME-BE02''. It returns de ID of the newly created process.

====DELETE apiv1/processes/PROCESS_ID====
It aborts a specific process (identified by PROCESS_ID) if it is not already in state ERROR. 

**Response:**

In case of HTTP status code 200, the response is a "Success" message. Otherwise the response is a "Failed" message. 

**Examples**:
  -  ''curl -X DELETE http://localhost:12345/apiv1/processes/20130917101910531_475'' - aborts the process 20130917101910531_475.



======Daemon======
The /apiv1/daemon resource makes available some management tasks.

====DELETE /apiv1/daemon====
The DELETE method on this resource stops the Bee daemon, by stopping services and killing running cluster jobs.

**Response:**

In case of status code 200, the result is a "Success" message. Otherwise a message informing about the error.

**Examples:**

  -  ''curl -i -X DELETE http://localhost:9999/apiv1/daemon'' - stops the Bee application.
 
====== REST Interface Security ======
to be implemented


======REST interface design======
The aim of this page is to describe the design principles of the BEE REST interface.

===General concepts===
Following the concept of REST, accessing resources with GET calls should not change the status of the system, just only query that. For adding new resources we should use POST, for updates PUT and for deleting the DELETE request.
 

The API version should be defined in the base URL: /apiv1

We should use simple short, noun resource identifiers like /apiv1/processes or /apiv1/workflows. And we should use a second URL for the specific resources like /apiv1/processes/PROCESS_ID or /apiv1/workflows/WORKFLOW_ID.

The complex, optional method parameters should be URL parameters after the resource like: /apiv1/processes?workflow="MyWorkflow"&offset=0&limit=10
The parameters of the POST and PUT methods should be JSON encoded objects.

===Responses===
All methods should return an appropriate HTTP status code:
  -  200 - OK: the request was successful
  -  400 - Bad Request: if some of the parameters are missing or wrong
  -  401 - Unauthorized: if the user provided wrong authentication header
  -  500 - Internal Server Error: if the parameters were valid but some error happens.
The response body should contain the expected data and data type (JSON, plain text,.. according the documentation of the method) in case of status code 200. Otherwise it should contain some error message that helps to solve the problem or at least contains some hints.

===The API===
  -  Processes: interface for processes
  -  Workflows: operations related to workflows
  -  Datasets: operations help managing datasets
  -  Recovery methods:

===Sources===
  -  RESTful API Design: Second Edition-http://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_webinar/
  -  Restful Web-Services Best Practices-http://soa.dzone.com/articles/restful-web-services-best
  -  HTTP Status Codes-http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
  -  Using REST-https://developers.google.com/translate/v2/using_rest
  -  GET Bucket logging-http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlogging.html
screeningBee Data Analysis Tools

User Tools

Site Tools

Page Tools
