API Sample Manifest

API - Sample manifest

This part of the API is currently being finalised so details may change from what is presented here. In particular, the information relating to the container element may vary slightly but the element itself will not be removed.

The following documents the sample manifest API, through which samples are registered with the system. The idea behind the manifests is that the Sanger Institute pre-generates a manifest, prints labels on the tubes or plates, and then ships them to a supplier; the supplier then fills the containers with their samples, fills the details of these samples in the manifest, and sends both of them back to the institute; once received, the sample manifest is uploaded to the system, updating the details of the samples within Sequencescape, and the physical samples are processed by the receiving laboratory.

So the API follows the same flow, in that you:

1. Create a manifest with "blank" information
2. Update the manifest with the correct information

Printing the labels is left to the client application.

Pre-requisites

In order to create a sample manifest the client application needs several pieces of information:

• A study, identified by a UUID, through which to create the manifest
• A supplier, identified by a UUID, that will be supplying the samples
• Whether to create a tube or plate manifest
• The number of containers that will be registered (plates are assumed to have 96 wells)

The first two pieces of information can be obtained through the API itself by accessing the appropriate resources, either through searches or by iterating over all records to identify the specific ones required. Once the UUIDs have been obtained they can be safely stored as these will not change.

In the following examples it can be assumed that:

• The study UUID is 22222222-3333-4444-5555-000000000000
• The supplier UUID is 33333333-1111-2222-3333-444444444444
• The API is located at http://www.example.com/api/1/

Creating a sample manifest

The first thing the client needs to do is retrieve the JSON for the study, by performing an HTTP GET request to the study URL, which is, by definition, http://www.example.com/api/1/22222222-3333-4444-5555-000000000000. The returned JSON will contain, at least, the following elements:

{
  "study": {
    "sample_manifests": {
      "actions": {
        "create_for_tubes": "http://www.example.com/api/1/22222222-3333-4444-5555-000000000000/sample_manifests/create_for_tubes",
        "create_for_plates": "http://www.example.com/api/1/22222222-3333-4444-5555-000000000000/sample_manifests/create_for_plates"
      }
    }
  }
}

It should now be obvious that the create_for_tubes action can be used to create tube manifests, and the create_for_plates will create plate manifests. Both of these respond to HTTP POST requests, just as a normal create action would.

So an HTTP POST, with the following JSON in its request body, to the create_for_tubes action would create a manifest for 5 tubes:

{
  "sample_manifest": {
    "supplier": "3333333-1111-2222-3333-444444444444",
    "count": 5
  }
}

Sending the same JSON body to create_for_plates would create 5 96 well plates, pre-registering 480 samples.

The response from either will contain the JSON for the manifest, first let's examine the common elements:

{
  "sample_manifest": {
    "actions": {
      "read": "http://www.example.com/api/1/00000000-1111-2222-3333-444444444444",
      "update": "http://www.example.com/api/1/00000000-1111-2222-3333-444444444444"
    },
    "study": {
      "actions": {
        "read": "http://www.example.com/api/1/22222222-3333-4444-5555-000000000000"
      }
    },
    "supplier": {
      "actions": {
        "read": "http://www.example.com/api/1/33333333-1111-2222-3333-444444444444"
      }
    },

    "uuid": "00000000-1111-2222-3333-444444444444",
    "state": "pending",
    "last_errors": null,

    "samples": [
      { 
        "container": { ... container specific information here ... },
        "sample": { ... sample information here ... }
      },
      ... 10 records in total here ...
    ]
  }
}

It should be obvious that the study and supplier relations link to the study and supplier that were used to create the manifest. And it should also be apparent that the top-level actions element contains the read and update actions for the sample manifest itself.

The samples element is a list of records that identify the container in which a particular sample exists, and the information for the sample itself. The contents of each sample element conforms to the JSON used by the sample part of the API regardless of whether the manifest is for tubes or plates.

The variations between the two types of manifest come in the contents of the container element. In the case of a tubes manifest the elements will look like this:

"container": {
  "barcode": "NT9999J"
}

For a plate manifest a sample is to be placed in a particular well on a particular plate; therefore the container element becomes:

"container": {
  "position": "A01",
  "barcode": "DN1234567T"
}

Here the container is the well at position A01 on the plate identified by the barcode.

Updating a sample manifest

coming soon