Developer:API
From myExperiment
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
General 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
All elements can be returned too:
http://www.myexperiment.org/workflow.xml?id=20&all_elements=yes
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 and search 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
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 |
