Skip to content

Instrument Control Web Services API

Jump to bottom Edit New page
fripp edited this page Apr 3, 2013 · 24 revisions
  • Introduction
  • [Security] (#Sec)
  • [LIMS Integration] (#LIMS)
  • [Web Services Behavior] (#WSB)
  • [HTTP Response Codes] (#HCODE)
  • [Sample Sheet Service] (#SSS)
  • [Sample Sheet Validate Function] (#SA_Val)
  • [Sample Sheet Import Function] (#SA_Imp)
  • [Sample Sheet Export Function] (#SA_Exp)
  • [Sample Sheet Update Function] (#SA_Upd)
  • [Sample Sheet Delete Function] (#SA_Del)
  • [Job Status Service] (#JSS)
  • [Plate Job Status Function] (#JOB_Stat)
  • [Acquisition Job Status Function] (#JOB_Aq)
  • [Reagent Mixing Job Status Function] (#JOB_Rea)
  • [Primary Analysis Job Status Function] (#JOB_PAStat)
  • [Primary Analysis Query Function] (#JOB_PAQuery)
  • [Transfer Status Query Function] (#JOB_Trans)

Introduction

This document describes the Instrument Control Web Services API provided by Pacific Biosciences. The API allows developers to access some of the functionality provided by the PacBio® System. The API includes functions for:

  • Registering plates
  • Obtaining job status information about different types of jobs

The latest version of the API and this documentation are available from the PacBio® Developer’s Network at http://www.pacbiodevnet.com.

Security

Pacific Biosciences does not currently enforce any access control at the web service level.

  • We assume that the instrument(s) and web services are hosted inside an intranet only, for security reasons.

LIMS Integration

The following example displays a typical use case of LIMS (Laboratory Information Management System) integration using the Instrument Control Web Services API.

  1. The LIMS creates and registers plates to the PacBio® System.
  2. The PacBio® System processes the plate job based on the imported sample sheet.
  3. The LIMS periodically queries the plate job status, as well as individual job acquisition status.
  4. The Primary Analysis Pipeline creates one base file for each acquisition job. Based on the results of the job status query, the LIMS decides how to process the Primary Analysis output files.

Web Services Behavior

The interface for the following services follow the RESTful (Representational State Transfer) model for web services. The status of an operation is communicated by way of the HTTP response code:

  • If the method indicates success, the body of the HTTP response may contain the result of the query, if there is any.
  • If a response includes data, the data is formatted in JSON (JavaScript Object Notation) format, unless otherwise specified.
  • If a request returns an error code, the body of the response contains a JSON object that describes the nature of the error.

HTTP Response Codes

###Return values for queries using the HTTP GET call:###

  • Return Value: 200 OK Explanation: The web service call returned successfully. The body of the response contains the query result.

  • Return Value: 404 Not Found Explanation: The object requested was not found.

  • Return Value: 413 Request Entity Too Large Explanation: The request will return a response that is too large for the client.

  • Return Value: 500 Internal Server Error Explanation: An internal error occurred while processing the request.

###Return values for queries using the HTTP PUT or POST call:###

  • Return Value: 200 OK Explanation: The PUT updated an existing object in the system. The PUT or POST operation was successful.

  • Return Value: 201 Created Explanation: The PUT created a new object on the system. The PUT or POST operation was successful.

  • Return Value: 400 Bad request Explanation: The contents of the PUT or POST were invalid and the data was rejected.

  • Return Value: 409 Conflict Explanation: The PUT or POST attempted to modify an existing object that cannot be modified. The PUT or POST operation was unsuccessful.

  • Return Value: 500 Internal Server Error Explanation: An internal error occurred while processing the request.

POST requests must have content-type multipart/form-data, and the object(s) being uploaded must be added as input type file.

Sample Sheet Service

The Sample Sheet Service includes functions to manage plate registration.

Important! Use port number 80 or 8081 when specifying the URL for the following functions.

Sample Sheet Validate Function

Use this function to run validation on the sample sheet being uploaded.

  • URL: /SampleSheet/Validate
  • Method: PUT or POST
  • Input Format: Well-formatted native sample sheet format (CSV). For formatting details, see the document Run Definition FIle Format. (Include link)
  • Returns: On success, includes a dictionary containing the barcode of the validated sample sheet, in JSON format.
  • Example: curl -s -H 'Expect: ' -T "filename_to_validate" http://host_ipaddress:8081/SampleSheet/Validate

Sample Sheet Import Function

Use this function to import a new sample sheet into the system, or to update an existing sample sheet with the same barcode ID (if updates are permitted.)

  • URL: /SampleSheet/Import
  • Method: PUT or POST
  • Input Format: Well-formatted native sample sheet format (CSV). For formatting details, see the document Run Definition FIle Format. (Include link)
  • Returns: On success, includes a dictionary containing the barcode of the imported (and validated) sample sheet, in JSON format.
  • Example: curl -s -H 'Expect: ' -T "filename_to_import" http://host_ipaddress:8081/SampleSheet/Import

Sample Sheet Export Function

Use this function to obtain a previously-imported sample sheet.

  • URL: /SampleSheet/plate_id
  • Method: GET
  • Parameters: plate_id: The plate ID of the sample sheet.
  • Returns: The sample sheet requested, in native sample sheet format (CSV).
  • Example: curl -s -H 'Expect: ' http://host_ipaddress:8081/SampleSheet/XY12345

Sample Sheet Update Function

Use this function to update an existing sample sheet.

  • URL: /SampleSheet/plate_id
  • Method: PUT or POST
  • Input Format: Well-formatted native sample sheet format (CSV). For formatting details, see the document Run Definition FIle Format. (Include link)
  • Parameters: plate_id: The plate ID of the sample sheet.
  • Returns: Success or failure is indicated through the HTTP response code.
  • Example: curl -s -H 'Expect: ' -T "filename_to_update" http://host_ipaddress:8081/SampleSheet/XY12345

Sample Sheet Delete Function

Use this function to delete an existing sample sheet.

  • URL: /SampleSheet/plate_id
  • Method: DELETE
  • Parameters: plate_id: The plate ID of the sample sheet.
  • Returns: Success or failure is indicated through the HTTP response code.
  • Example: curl -s -H 'Expect: ' -X DELETE http://host_ipaddress:8081/SampleSheet/XY12345

Job Status Service

The Job Status Service includes functions to obtain the status of different types of jobs. The return type for these queries is a JobState structure, which includes two fields:

  • JobStatus: The JobStatus enumeration value, which can be Ready, Running, Aborted, Failed or Complete.
  • CustomState: An optional text string that provides additional information about the job state.

Following is an example JSON structure for JobStatus:

{ Status: Ready, CustomState: “Ready to run.” }

Plate Job Status Function

Use this function to obtain the job status of a plate job.

  • URL: /Jobs/Plate/plate_id/Status
  • Method: GET
  • Parameters: plate_id: The plate ID of the sample sheet.
  • Returns: A JobState structure in JSON format.
  • Example: curl -s -v http://host_ipaddress:8081/Jobs/Plate/platebarcode/Status

Acquisition Job Status Function

Use this function to obtain the job status of an acquisition job. The JobStatus object that is returned can include information about the status of multiple jobs.

  • URL: /Jobs/Collection/plate_id/samplewell_num/Status
  • Method: GET
  • Parameters: plate_id: The plate ID of the sample sheet, samplewell_num: The sample well number.
  • Returns: An array of JobState structures, in JSON format.

Reagent Mixing Job Status Function

Use this function to obtain the job status of a reagent mixing job.

  • URL: /Jobs/ReagentMix/plate_id/samplewell_num/Status
  • Method: GET
  • Parameters: plate_id: The plate ID of the sample sheet, samplewell_num: The sample well number.
  • Returns: A JobState structure, in JSON format.

Primary Analysis Job Status Function

Use this function to obtain the job status of a primary analysis job. The JobStatus object returned can include information about the status of multiple jobs.

  • URL: /Jobs/PrimaryAnalysis/plate_id/samplewell_num/Status
  • Method: GET
  • Parameters: samplewell_num: The number of the sample well being analyzed.
  • Returns: A JobState structure, in JSON format.

Primary Analysis Query Function

Use this function to obtain information about a primary analysis job.

  • URL: /Jobs/PrimaryAnalysis/Query
  • Method: GET
  • Parameters (Optional):
    • after: The earliest date and time to search to.
    • before: The latest date and time to search from.
    • max: The maximum number of entries to return, currently 108.
    • status: The status of the job to search for. Allowed values: None, Pending, Ready, Running, Interrupted, Aborted, Failed, Complete, and SpecificState.
    • Parameters are given as GET arguments.
  • Returns: An array of objects (in JSON format) that contain the following members:
    • WhenModified: The date and time the job was last modified.
    • JobStatus: The current job status.
    • OutputFilePath: The output path for the analysis job.
    • AcquisitionNumber: The acquisition ID.
    • Well: The sample well for this job.
    • Plate: The barcode of the plate used.
  • Examples:
    • /Jobs/PrimaryAnalysis/Query?status=Complete&before=2010-03-15&after=2010-01-15&max=100
    • curl -s -H 'Expect: ' "http://host_ipaddress:8081/Jobs/PrimaryAnalysis/Query?status=Complete&before=2010-03-15&after=2010-01-15&max=100"

Transfer Status Query Function

Use this function to obtain information about a transfer of data for secondary analysis

  • URL: /Jobs/TransferQuery
  • Method: GET
  • Parameters (Optional):
    • after: The earliest date and time to search to.
    • before: The latest date and time to search from.
    • max: The maximum number of entries to return, currently 108.
    • status: The status of the job to search for. Allowed values: None, Pending, Ready, Running, Interrupted, Aborted, Failed, Complete, and SpecificState.
    • Parameters are given as GET arguments.
  • Returns: An array of objects (in JSON format) that contain the following members:
    • WhenModified: The date and time the job was last modified.
    • JobStatus: The current job status.
    • OutputFilePath: The output path for the analysis job.
    • AcquisitionNumber: The acquisition ID.
    • Well: The sample well for this job.
    • Plate: The barcode of the plate used.
  • Examples:
    • /Jobs/PrimaryAnalysis/Query?status=Complete&before=2010-03-15&after=2010-01-15&max=100
    • curl -s -H 'Expect: ' "http://host_ipaddress:8081/Jobs/PrimaryAnalysis/Query?status=Complete&before=2010-03-15&after=2010-01-15&max=100"

Sample C# code to determine when a cell has been transferred, using TransferQuery:

using System.IO;
using System.Net;
using System.Web.Script.Serialization;

static bool MatchRunIdAndCollectionName(string outputFilePath, string runId
                                      , string collectionName)
{
    if (outputFilePath == null) return false;
    var afolder = outputFilePath.Split('/');
    int len = afolder.Length;
    var folderName = afolder[len - 2].Replace("%20", " ");
    return (folderName == runId && afolder[len - 1] == collectionName);
}

// @param uploadDataPath looks like "\usmp-data3\vol53\RS_DATA_STAGING"
void LookForCompleteCell(string uploadDataPath) {
   DirectoryInfo di = new DirectoryInfo(uploadDataPath);
// Only look for look 1 metadata, to even know what to look for
   FileInfo[] files = di.GetFiles("m*_s1_p0.metadata.xml"
     , SearchOption.AllDirectories);
   JavaScriptSerializer jSerialize = new JavaScriptSerializer();

   foreach (FileInfo file in files)
   {
      //e.g m120201_025018_42142_c100208912554400001515048402131234_s1_p0
      string context = file.Name.Split('.')[0];
      string dates = actx[0].Substring(1), times = actx[1], instrument = actx[2] , look = actx[4];
      string yr = dates.Substring(0, 2)
         , mo = dates.Substring(2, 2)
         , dy = dates.Substring(4, 2)
         , mi = times.Substring(2, 2)
         , sec = times.Substring(4, 2);
      string safter = "20" + yr + "-" + mo + "-" + dy + "T" + hr + ":" + mi + ":" + sec;
      var runId = di.Parent.Name;//would be something like 20120131_ETv26097p_scales_442
      var plate = runId.Substring(0, runId.LastIndexOf('_'));
      string serviceUrl =
         "http://pap01-" + instrument
         +
         ":8081/Jobs/TransferQuery/Query?status=Complete&platform=Windows&after="
         + safter;
      HttpWebRequest webRequest = WebRequest.Create(serviceUrl) as HttpWebRequest;
      HttpWebResponse webResponse = webRequest.GetResponse() as HttpWebResponse;
      StreamReader sr = new StreamReader(webResponse.GetResponseStream());
      var aj = jSerialize.Deserialize<List<Dictionary<string, object>>>(sr.ReadToEnd());
      var status = aj.Find(d
                            => MatchRunIdAndCollectionName((string)d["OutputFilePath"], runId , collectionName)
                               && ("s" + d["IndexOfLook"]) == look);
      if (status == null) continue;
      //At this point, we have both look 1 and look 2 (if this is a 2 look movie).
      //This SMRT Cell is ready for analysis
   }
}

For Research Use Only. Not for use in diagnostic procedures. © Copyright 2010 - 2013, Pacific Biosciences of California, Inc. All rights reserved. Information in this document is subject to change without notice. Pacific Biosciences assumes no responsibility for any errors or omissions in this document. Certain notices, terms, conditions and/or use restrictions may pertain to your use of Pacific Biosciences products and/or third party products. Please refer to the applicable Pacific Biosciences Terms and Conditions of Sale and the applicable license terms at http://www.pacificbiosciences.com/licenses.html.

DevNet                                                                                                                                                                                                                Terms of Use | Trademarks | Contact Us

Add a custom sidebar
Clone this wiki locally