Developer:API

From myExperiment
Jump to: navigation, search

Developer API Documentation


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

Resource Index Create Read Update Delete Elements
Announcements Implemented Planned Implemented Planned Planned Listed
Citations Planned Planned Implemented Planned Planned Listed
Comments Implemented Implemented Implemented Not planned Implemented Listed
Credits Implemented Planned Implemented Not planned Planned Listed
Curation events Implemented Planned Implemented Not planned Planned Listed
Downloads Planned Not planned Implemented Not planned Not planned Listed
Experiments Planned Planned Implemented Planned Planned Listed
Externals (Packs) Planned Implemented Implemented Implemented Implemented Listed
Favourites Planned Implemented Implemented Implemented Implemented Listed
Files Implemented Implemented Implemented Implemented Implemented Listed
Groups Implemented Planned Implemented Planned Planned Listed
Internals (Packs) Planned Implemented Implemented Implemented Implemented Listed
Jobs Planned Planned Implemented Planned Planned Listed
Licenses Implemented Planned Implemented Planned Planned Listed
Messages Implemented Planned Implemented Planned Planned Listed
Ontologies Implemented Implemented Implemented Implemented Implemented Listed
Packs Implemented Implemented Implemented Implemented Implemented Listed
Pictures Planned Planned Implemented Planned Planned Listed
Predicates Implemented Implemented Implemented Implemented Implemented Listed
Ratings Planned Planned Implemented Implemented Implemented Listed
Relationships Implemented Implemented Implemented Not planned Implemented Listed
Reviews Planned Planned Implemented Planned Planned Listed
Runners Planned Planned Implemented Planned Planned Listed
Tags Implemented Planned Implemented Planned Planned Listed
Taggings Implemented Implemented Implemented Planned Planned Listed
Types Implemented Planned Implemented Planned Planned Listed
Users Implemented Planned Implemented Planned Planned Listed
Workflows Implemented Implemented Implemented Implemented Implemented Listed

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