Examples for testing the REST Interface on the development server:

Checkout the example workflows from Subversion:

cd ~/stage/bee/
svn co svn://svn.code.sf.net/p/screeningbee/code/trunk/project screeningbee-project

Check the status of the queue before submission:

qstat

Start a new workflow:

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

Check running workflows:

/usr/bin/curl http://localhost:12345/apiv1/processes

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.

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

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:

1. wget http://localhost:9999/apiv1/processes - gives the status of the submitted processes.

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:

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

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:

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

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:

curl -X POST --data-urlencode workflow@src/test/resources/functional/workflows/MultipleModules_vars_val.xml http://localhost:9999/apiv1/processes

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.

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

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.

curl -X POST --data-urlencode "workflow.id=20130620095251781-41392" --data-urlencode "RawImages=0bCDME-BE02" http://localhost:9999/apiv1/processes

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.

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:

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

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

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:

1. curl -i -X DELETE http://localhost:9999/apiv1/daemon - stops the Bee application.

to be implemented

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

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.

All methods should return an appropriate HTTP status code:

1. 200 - OK: the request was successful
2. 400 - Bad Request: if some of the parameters are missing or wrong
3. 401 - Unauthorized: if the user provided wrong authentication header
4. 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.

1. Processes: interface for processes
2. Workflows: operations related to workflows
3. Datasets: operations help managing datasets
4. Recovery methods:

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