Skip to content

API Submission

Jump to bottom
mattdenner edited this page May 17, 2011 · 8 revisions

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 a submission from a submission template, the latter defining the flow of work to be done on the samples attached to the former.

The component parts of a submission 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

The process of creating a submission is a multi-step process:

  1. Create a submission from a template by providing at least the project and study to be used
  2. Update the information for a submission to provide all of the information required for the laboratory
  3. Submit the submission for work to be performed

It is possible to reduce this to two steps by providing all of the necessary information at the point of creation, leaving only the need to submission the completed submission. This flow allows submissions to be updated as their samples become available, even if this covers several days.

Creating a submission

Because submissions 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 a submission 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

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

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

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

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

{
  "submission": {
    "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

{
  "submission": {
    "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",
      "submit": "http://www.example.com/api/1/11111111-2222-3333-4444-555555555555/submit"
    },
    "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"
      }
    ],
    "requests": {
      "actions": {
        "read": "http://www.example.com/api/1/11111111-2222-3333-4444-555555555555/requests"
      }
    }
  }
}

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

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.

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 submission. These will be exposed in a future release of the API.

Updating a submission

Once the submission has been created, and until it has been submitted, 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 submission, 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

{
  "submission": {
    "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.

Submitting the submission

coming soon

Clone this wiki locally