Overview

Use our REST API, based on open standards, to build third party applications which can use any web development language to access the API.

Using the API, users can sign in and grant your application the right to make calls on their behalf. Then, through the API, your application can access Collaborative PL-Science resources such as experiments, workflows, webservices, researchers data.

You should be familiar with REST architecture before writing an integration. Good REST resources abound on the internet. Read this overview page to gain a good understanding of Collaborative PL-Science's REST implementation.

Schema

All API access is over HTTPS, and accessed from the api.plscience.com domain. All data is sent and received as JSON.

$ curl -i https://api.plscience.com/experiments

HTTP/1.1 200 OK
Server: nginx
Date: Fri,  Nov 2014 20:59:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

[]

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i "https://api.plscience.com/experiment/12/webservices?domain=rna"

In this example, the ‘12’ value is provided for the :experiment parameter in the path while :domain is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’:

$ curl -i -u username -d '{"contexts":["biology"]}' https://api.plscience.com/workflows

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

Sending invalid JSON will result in a 400 Bad Request response.

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Problems parsing JSON"}

Sending invalid fields will result in a 422 Unprocessable Entity response.

HTTP/1.1 422 Unprocessable Entity
Content-Length: 149

{
 "message": "Validation Failed",
 "errors": [
   {
     "resource": "Experiment",
     "field": "id",
     "code": "missing_field"
   }
 ]
}

Trying to access data without permissions in a 403 Permission denied.

HTTP/1.1 403 Permission denied
Content-Length: 31

{"message":"Permission denied"}

URI Methods

A given endpoint or resource has a series of actions (or methods) associated with it. The Collaborative PL-Science service supports these standard HTTP methods:

Endpoints and Resources

Collaborative PL-Science supports several endpoints. These endpoints may or may not have additional resources. The table below lists the endpoints and their associated resources.