Skip to content

API Submission

Jump to bottom
mattdenner edited this page Jan 24, 2012 · 8 revisions

NOTE: This page details the next version of this API that will arrive in 5.01.0 or 5.02.0 and allows for higher degrees of sample pooling.

Submitting samples for laboratory work

Once samples, and their associated containers, have been registered with Sequencescape, either through the UI or via the sample manifest API the next stage is to request laboratory work on them. To do so you create an order from an order template, the latter defining the flow of work to be done on the samples attached to the former. Once you have a number of orders you can put them into a submission, which generates the requested work structure and defines them as a pool.

The component parts of an order are:

  • A project
  • A study
  • A list of sample containers, or a pre-registered group of containers
  • A number of options that change the behaviour of the laboratory work

Creating an order and building a submission is a multi-step process:

  1. Create an order from a template by providing at least the project and study to be used
  2. Update the information for the order to provide all of the information required for the laboratory
  3. Create a submission with the orders you have built
  4. Submit the submission for the work to be done

It is possible to reduce the first two steps by providing all of the necessary information at the point of creation. The flow above allows orders to be updated as their samples become available, even if this covers several days, before finally adding them to a submission. Note that once an order is part of a submission it cannot be modified.

Creating an order

Because orders are such a core part of Sequencescape, and more importantly the processes followed by the laboratories, API clients create them from templates, which pre-define the workflow the samples will follow. So create an order a client must have the UUID of the template they wish to use and, for this example, we'll assume that to be 00000000-1111-2222-3333-444444444444.

Reading the template URL will return JSON that will contain a create action:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "order_template": {
    "actions": {
      "read": "http://www.example.com/api/1/00000000-1111-2222-3333-444444444444"
    },
    "orderss": {
      "actions": {
        "create": "http://www.example.com/api/1/00000000-1111-2222-3333-444444444444/orders"
      }
    },

    "uuid": "00000000-1111-2222-3333-444444444444",
    "name": "Simple sequencing"
  }
}

It should be apparent that an HTTP POST to the create action under the orders element will create an order. The client must provide both a project and study UUID in order for an order to be validly created: financial charges are levied against the project, and the study is used for reporting results. So, a valid order can be created with the following HTTP POST request:

POST /api/1/00000000-1111-2222-3333-444444444444/orders HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: WTSISignOn=authentication-token

{
  "order": {
    "project": "22222222-3333-4444-5555-000000000001",
    "study": "22222222-3333-4444-5555-000000000000"
  }
}

And the response will be of the form:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "order": {
    "actions": {
      "read": "http://www.example.com/api/1/11111111-2222-3333-4444-555555555555",
      "update": "http://www.example.com/api/1/11111111-2222-3333-4444-555555555555"
    },
    "study": {
      "actions": {
        "read": "http://www.example.com/api/1/22222222-3333-4444-5555-000000000000"
      },
      "name": "Testing submission creation"
    },
    "project": {
      "actions": {
        "read": "http://www.example.com/api/1/22222222-3333-4444-5555-000000000001"
      },
      "name": "Testing submission creation"
    },
    "assets": [],
    "request_types": [
      {
        "uuid": "99999999-1111-2222-3333-000000000000",
        "name": "Library creation"
      },
      {
        "uuid": "99999999-1111-2222-3333-000000000001",
        "name": "Paired end sequencing"
      }
    ]
  }
}

The sections of this should be fairly self-explanatory:

  • study contains the information on the study used
  • project contains the information on the project used
  • request_types contains the work request types that will be performed, in order
  • assets is an array of the sample containers that will be used in the submission

NOTE: There is information missing from the request_types element that is quite critical, and this is being addressed. Without knowing what options are available it is hard for clients to know what to provide to complete the order. These will be exposed in a future release of the API.

Updating an order

Once the order has been created, and until it has been added to a submission, it can be updated to modify the sample containers that will be used and the work request options. As usual, an HTTP POST request to the update action for a specific order, with the correct JSON, can be used to perform the updates.

First there are two mechanisms for specifying the sample containers that will be used:

  1. Assign their UUIDs in an array to the assets element.
  2. Use a pre-created group of sample containers (called an asset group)

The latter can be done by setting the asset_group_name element to the name of the asset group to use; setting assets in this case will be considered an error. If the name specified does not exist, and sample containers are specified through the assets element, the group will be created with the specified name and will contain the sample containers set. If the asset_group_name is unspecified then assigning assets is required and the asset group name will be assigned automatically.

So, an example of assigning assets would be:

PUT /api/1/11111111-2222-3333-4444-555555555555 HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: WTSISignOn=authentication-token

{
  "order": {
    "assets": [ "99999999-1111-2222-3333-444444444444" ],
    "asset_group_name": "A more meaningful asset group name"
  }
}

The JSON response will contain details of the sample container referenced by UUID 99999999-1111-2222-3333-444444444444, rather than just the UUID itself.

It should be noted that to add more sample containers you need to specify all of the UUIDs again. Although this may be a disadvantage if all you are doing is adding, it does mean that to remove any you simply do not need to specify their UUIDs on an update.

Each work request type returned in the request_type element of the JSON has a particular set of options that can be changed. To do this the client can make an HTTP PUT request with the appropriate values set in the request_options JSON. The following are a list of all request options (in dotted notation) that can be set, along with their legal values.

Sequencing options

  • read_length varies for non-HiSeq (legal values: 37, 54, 76, 108) and HiSeq (legal values: 50, 75, 100) sequencing requests
  • fragment_size_required.from and fragment_size_required.to

Library creation options

  • library_type can be one of "No PCR", "High complexity and double size selected", "Illumina cDNA protocol", "Agilent Pulldown", "Custom", "High complexity", "ChiP-seq", "NlaIII gene expression", "Standard", "Long range", "Small RNA", "Double size selected", "DpnII gene expression", "qPCR only"

PacBio

  • insert_size can be one of 200, 250, 500, 1000, 2000, 4000, 6000, 8000, 10000
  • sequencing_type can be one of "Standard","Strobe","Circular"

It is safe to assume that, if the work request type is present in the order JSON, then the associated options are required.

NOTE: In a future release of the API the information about what request options are applicable for the order, will be available in the order JSON itself.

So, to set the required options for the example order the client would make the following HTTP PUT request:

PUT /api/1/11111111-2222-3333-4444-555555555555 HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: WTSISignOn=authentication-token

{
  "order": {
    "request_options": {
      "read_length": 76,
      "library_type": "No PCR",
      "fragment_size_required": {
        "from": 100,
        "to": 200
      }
    }
  }
}

Note that, although these have been discussed as separate updates, they could be combined into a single HTTP PUT, or they could be specified at the point of order creation.

Creating the submission

Once you have one or more orders you can place them in a submission, which is responsible for generating the appropriate requests for work in the laboratories and for defining how the samples will be pooled. In the case of the latter, you can imagine that an order allows you to define a pool for your samples, and that a submission allows for higher pooling.

NOTE: At the moment creating a submission from many orders requires all of the orders to be for identical work. That is, although the study, project and assets can vary between them, all other details must be the same.

To place our order into a new submission we simply have to perform the following HTTP POST:

PUT /api/1/submissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: WTSISignOn=authentication-token

{
  "submissions": {
    "orders": [
      "11111111-2222-3333-4444-555555555555"
    ]
}

The response will look something like this:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "submission": {
    "actions": {
      "read": "http://www.example.com/api/1/11111111-2222-3333-4444-666666666666",
      "update": "http://www.example.com/api/1/11111111-2222-3333-4444-666666666666",
      "submit": "http://www.example.com/api/1/11111111-2222-3333-4444-666666666666/submit"
    },
    "orders": [
      {
        "actions": {
          "read": "http://www.example.com/api/1/11111111-2222-3333-4444-555555555555"
        }
      }
    ],
    "requests": []
  }
}

For the moment we can ignore the requests element, which will eventually list of the individual work request instances and can be used to track the progress of the sample containers through the laboratories.

The important section is the actions which detail the URLs that should be used to read, update and submit the submission. An HTTP POST to the submit action will cause the submission to be completed, as detailed in the final section of this document.

Until the submission is submitted clients can update the list of orders contained within the submission. However, be aware that you will need to maintain the entire list; that is, if you want to add an order you must specify all the UUIDs of the orders, including those that already list in the submission.

Submitting the submission

Once all of the information for a submission has been set it is only a matter of performing an HTTP POST request to the submit action to finalise the submission and get the work started. For example, to submit the submission documented here would require the following client request:

POST /api/1/11111111-2222-3333-4444-666666666666/submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: WTSISignOn=authentication-token

{ "submission": { } }

The response will be 200 OK if this was successful, otherwise an error will be returned in the body of the response.

Once a submission has been successfully submitted it cannot be modified, any attempt to do so will cause an error response from the API. At the same time, the work requests that are required for the submission will be generated and can be accessed through the requests element of the JSON for the submission.

Clone this wiki locally