Developer:API
Developer API Documentation
Contents
If you wish to experiment with the API using test data, please use http://sandbox.myexperiment.org/ instead of the main site. If you require any support or requests with regards to the myExperiment sandbox, please contact Don Cruickshank.
The interactive HTTP request builder at http://sandbox.myexperiment.org/mashup/api is a great place to try out REST requests.
myExperiment supports secure requests using OAuth. See OAuth for how to set up your own client applications to make secure HTTP requests to the API using OAuth. Though not as secure, you may also use a session cookie to obtain access to a particular myExperiment account. This process is described in Simple cookie authentication.
Resources
Components
The API for finding, creating and organizing Taverna components is described here: Developer:Components
Search
The API search facility uses the same search engine as the main website. It is available from the following URL:
http://www.myexperiment.org/search.xml?query=bioaid
Particular types can be specified by the type query option:
http://www.myexperiment.org/search.xml?query=bioaid&type=workflow
You can specify multiple types to search over, e.g.:
http://www.myexperiment.org/search.xml?query=example&type=workflow,pack
Currently supported search types are:
- user
- workflow
- file
- group
- pack
The results can be paged through by using the num and page options:
http://www.myexperiment.org/search.xml?query=example&type=workflow,pack&num=5&page=2
Element selection
The elements within each REST response can be tailored to include only the parts of the response of interest. This saves bandwidth and response time!
http://www.myexperiment.org/workflow.xml?id=20&elements=title,description
A listing of elements that can be returned for a particular resource can be found by clicking on the appropriate link in the Elements column of the table above.
All elements can be returned to see which elements can be selected:
http://www.myexperiment.org/workflow.xml?id=20&all_elements=yes
Please do not use all_elements in your code! We may restrict access to this feature once sufficient documentation exists for all the different elements.
Versions
For objects that have versions (e.g. Workflows), you may specify the specific version to be worked on by including version in the URI query. For example:
http://www.myexperiment.org/workflow.xml?id=20&version=1
Sorting
Index requests can be sorted. By default, these results are sorted by ascending creation order but sorting by creation time (created), update time (updated), title (title) and name (name) is also possible. In addition, the results can be returned in reverse order.
http://www.myexperiment.org/workflows.xml?sort=title
http://www.myexperiment.org/files.xml?sort=title&order=reverse
Pagination
For the index requests, a default maximum of 25 results is shown. This can be raised to 100 by using adding num to the query. A particular page of results can be selected by adding page to the query.
http://www.myexperiment.org/workflows.xml?num=50&page=2
Privileges
Some resources can be made private or shared only with a subset of myExperiment. For these resources, the privileges element is used to manage them. See API permissions for further details.
Redirections
There are two API requests that can be made that will return a redirect (HTTP 307 status) to the requested REST access URI.
"Who am I?"
This request will require authentication with the REST API. Once successful authentication has taken place, a redirect is returned that refers to the REST access URI of the authenticated user.
For example:
http://www.myexperiment.org/whoami.xml
The above URL along with Don Cruickshank's credentials will redirect to:
http://www.myexperiment.org/user.xml?id=22
REST Access URI
This request takes the URL of a myExperiment resource, e.g. a workflow, and will then redirect to the REST access URL for that resource.
For example:
http://www.myexperiment.org/rest-access.xml?resource=http://www.myexperiment.org/users/22
will redirect to:
http://www.myexperiment.org/user.xml?id=22
Index filtered by tag
For indices of taggable items, the index can be filtered on a particular tag.
http://www.myexperiment.org/workflows.xml?tag=bioaid
API version
The version of the REST API that the server uses can be requested by including api_version in the query.
http://www.myexperiment.org/workflows.xml?api_version=yes
Error responses
The general format of an error response from the REST API is an XML document with an error element. The code attribute contains a number that determines the class of error. The message attribute of the error element contains a human readable message describing the error.
Example error response:
<?xml version="1.0" encoding="UTF-8"?> <error message="Resource not found" code="404"/>
Error messages:
| Message | Code |
|---|---|
| Resource not found | 404 |
| Not authorized | 403 |
| Resource not versioned | 400 |
| Resource version not found | 404 |
| Service unavailable | 503 |
