Secondary Analysis Web Services API v2.2.0

Joey Karalius edited this page Aug 1, 2014 · 13 revisions
Clone this wiki locally

Introduction

This document describes the Secondary Analysis Web Services API provided by Pacific Biosciences. The API allows developers to search, submit and manage secondary analysis jobs, data, results, and user accounts.

Secondary Analysis Web Services follow the REST (Representational State Transfer) model for web services, and use the JSON (JavaScript Object Notation) format. The web services:

  • Run as the server-side layer for managing secondary analysis jobs.
  • Maintain data integrity in the secondary analysis database and file system.
  • Act as a layer on top of SMRT Pipe, the lower-level code that performs secondary analysis processing.
  • Support AJAX access from web clients and can be used from the command line with wget or curl; from scripting languages (PHP, Python® , PERL), and from Java® and C#® programming languages.

The API includes functions for:

  • Managing reference sequences
  • Managing user accounts and passwords
  • Managing groups of users
  • Managing instrument output (SMRT Cell data)
  • Managing secondary analysis jobs
  • Managing protocols
  • Validating sample sheets
  • Managing settings

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

Security

  • Anonymous read-only access to web services is enabled by default.
  • Services that create and modify data require authentication.
  • Authentication is enforced for administrator, scientist and technician-level access and cannot be disabled.
  • An application setting (restrictAccess) in the web.xml file turns on or off authentication for all those web services not solely for administrators.

Overview

Secondary Analysis Web Services API:

  • Run in or under a standard Linux®/Apache™ environment, and can be accessed from Windows®, Mac OS® or Linux® operating systems.
  • Require MySQL® software.
  • Are installed as part of the secondary analysis system, and require a one-time configuration. Any additional changes can be made using SMRT Portal.
  • Require that SMRT Pipe be correctly configured and working.

Web Services Behavior

  • URLs and parameters are all case-sensitive.

  • Most requests use the HTTP GET command to retrieve an object in JSON (JavaScript Object Notation) format: GET data to view details of an object: /{objects}/{id_or_name} Example: curl http://{server}/smrtportal/api/jobs/12345

  • Deleting objects uses the HTTP DELETE command: DELETE data: /{objects}/{id_or_name}. Example: curl -X DELETE -u administrator:somepassword http://{server}/smrtportal/api/jobs/12345

  • Saving objects to the server, manipulating objects, and operating on the server: These use the HTTP POST command common to standard HTML forms. This is not the same as for file uploads, which use a different mime type (multipart form data). In this case, the request body consists of key-value form pairs. POST data to create a new object: /{objects}. Example:

curl -d 'data={the job returned from the GET method, with some edits}' http://{server}/smrtportal/api/
jobs/12345
  • Saving objects to the server also supports the PUT and POST commands with alternative content-types, such as application/json and text/xml. In this case, the request body consists of JSON or XML, and contains no key-value form pairs: PUT/POST data to save/update objects: /{objects}

  • Most of the time you use /{objects}/create for both ways of saving objects.

  • Web services requiring authentication use the HTTP header’s Authorization feature. Example: curl –u “janeuser:somepassword” http://server/secret/sauce. Alternatively, you could log in using the users/log-on method and store the cookie for use with future web service calls.

  • Creating objects can be done using an HTTP POST using the /create method, or by using an HTTP PUT with JSON or XML as the request body. The PUT method is considered more of a REST “purist” approach, whereas POST is more widely supported by web browsers.

  • By default, most web services return JSON. However, it’s possible in most cases to change the result format by adding an Accept header to the request. Most methods will support Accept: text/xml as well as application/json, text/csv and text/tsv (tab-separated values).

Some examples:

JSON (default):

$ curl http://localhost:8080/smrtportal/api
{
  "success" : true,
  "message" : "Web services are alive"
}

XML:

$ curl -H "Accept: text/xml" http://localhost:8080/smrtportal/api
<?xml version="1.0" encoding="UTF-8"?>
<notice>
     <success>true</success>
     <message>Web services are alive</message>
</notice>

Comma-separated values:

$ curl -H "Accept: text/csv" http://localhost:8080/smrtportal/api
"message","success"
"Web services are alive","true"

Tab-separated values:

$ curl -H "Accept: text/tsv" http://localhost:8080/smrtportal/api
message success
Web services are alive  true

And back to JSON:

$ curl -H "Accept: application/json" http://localhost:8080/smrtportal/api
{
  "success" : true,
  "message" : "Web services are alive"
}

Passing Arguments

  • Arguments that are primitive types can be passed like the standard HTTP POST parameters: param1=value1&param2=value2

  • Arguments that are objects should be serialized as JSON: param1={“name1”:“value1”,“name2”:“value2”}

  • When using an HTTP PUT, simply pass the JSON or XML object in the request body: {“name1”: “Value1”, “name2”: “Value2”}

Date and Time Format

  • All dates and times are in the ISO 8601 Universal Time format.

HTTP Response Codes

Success Conditions

When successful, a web services call returns an object or list of objects serialized as JSON, unless a different format is requested using an Accept header. You can deserialize the object in any language as a dictionary/hashtable, a list, or a list of dictionary/hashtables. For more advanced use, you can create custom, strongly-typed objects.

For service calls that don’t return data from a server, a Notice message object with a uniform signatured is returned. For example: {“success”: true, “message”: “It worked”}

  • Return Value: 200 OK Explanation: The web service call returned successfully. The body of the response contains the requested JSON object. For function calls, the response may be a simple status message object.

  • Return Value: 201 Created Explanation: The web service created a new object on the server. A simple PrimaryKey object is returned, such as: {“idName”:”id”,”idValue”:12345}. The response will contain a header: Location: http://where/the/new/object/is

Error Conditions

When errors occur, the web services return an HTTP error code. The body of the response contains a standard JSON object that can be uniformly deserialized as a strongly typed object, or left as a dictionary/hashtable. For example: {“success”:false, “type”:”IllegalArgumentException”, “message”:“Job id cannot be null”}

  • Return Value: 400 Bad request Explanation: The arguments were incorrect, or the web service was called incorrectly.

  • Return Value: 403 Forbidden Explanation: The web service requires authentication, and the credentials in the HTTP header’s Authorization section were rejected.

  • Return Value: 404 Not Found Explanation: The search or web service call did not find the requested object.

  • Return Value: 409 Not Modified Explanation: The attempt to update or delete an object failed.

  • Return Value: 413 Request Entity Too Large Explanation: When searching a large database table, there may be practical limits to how many records can be returned. The query asked for too many records.

  • Return Value: 500 Internal Server Error Explanation: An internal error occurred.

Search Conventions

Lists of objects are retrieved using either the HTTP GET or POST commands. For objects with a small number of members, a JSON list is returned. Searching and filtering are possible through web services; see the documentation for the jqGrid plugin at http://www.trirand.com/jqgridwiki/.

GET the full list: /jobs

For objects with a large number of records (such as secondary analysis jobs and instrument output), results are paged. A wrapper object specifies the page number, total number of records, rows per page, and the list of objects themselves. The data structure is taken directly from the jqGrid plugin; for details see http://www.trirand.com/blog. Following is a sample structure: {“page”:1,“records”:50,“total”:510,”rows”:[{object1},{obj2}]} where:

  • page is the current page.
  • records is the number of rows on the current page.
  • total is the total number of rows.
  • rows is a list of objects for the current page.

Usage

  • GET the first page: /{objects} Example: curl http://{server}/smrtportal/api/jobs

  • POST search or filtering options to the same url: /{objects} Example: curl -d 'options={"page":2,"rows":10,"sortOrder":"desc","sortBy":"jobId"}' http://{server}/smrtportal/api/jobs

The set of search and filtering parameters available is extensive, flexible, and is also derived from the jqGrid plugin. Key options include:

  • Option: page Values: int Description: Page number, starting from 1.

  • Option: rows Values: int Description: Rows per page. If the requested number is too large, a 413 Request Entity Too Large error is generated.

  • Option: sortOrder Values: asc or desc Description: Sort order, ascending or descending.

  • Option: sortBy Values: String; object property name Description: ID of the column property to sort on. Example: JobId.

Arguments can be passed as JSON objects. For example: options={“sortOrder”:“asc”, “sortBy”:“name”, “page”:1}

Examples

Commonly-used methods include sample curl commands and sample returned values. The examples include a user named administrator and a PacBio instrument located at http://pssc1:8080/.

Reference Service

The References Service includes functions that you use to manage the reference sequences used in secondary analysis. (Reference sequences are used to map reads against a reference genome for resequencing and for filtering reads.)

List References Function

Use this function to list the reference sequences available on the system.

  • URL: /reference-sequences
  • Method: GET or POST
  • Parameters: options=SearchOptions (Only sortOrder and sortBy are supported.)
  • Returns: PagedList<ReferenceEntry>

Reference Details Function

Use this function to obtain details about a specific reference sequence.

  • URL: /reference-sequences/{id}
  • Method: GET
  • Parameters: id=string
  • Returns: ReferenceEntry

List References by Type Function

Use this function to list the reference sequences available on the system by their type.

  • URL: /reference-sequences/by-type/{name}
  • Method: GET or POST
  • Parameters:
    • name= control or name=sample
    • options=SearchOptions (Only sortOrder, sortBy and columnNames are supported.)
  • Returns: PagedList<ReferenceEntry>

Create Reference Function

Use this function to create a new reference sequence.

  • URL: /reference-sequences/create (Using POST), /reference-sequences (Using PUT)
  • Method: POST or PUT
  • Parameters:
    • data=ReferenceSequence (Using POST)
    • ReferenceSequence (Using PUT)
  • Returns: PrimaryKey

Save Reference Function

Use this function to save a reference sequence.

  • URL: /reference-sequences/{id}
  • Method: POST or PUT
  • Parameters:
    • id=string
    • data=ReferenceSequence
  • Returns: A notice message object

Delete Reference Function

Use this function to delete a reference sequence.

  • URL: /reference-sequences/{id}
  • Method: DELETE
  • Parameters: id=string
  • Returns: A notice message object

List Reference Dropbox Files Function

Use this function to list the reference files located in the Reference Sequence Dropbox.

  • URL: /reference-sequences/dropbox-files
  • Method: GET
  • Returns: List<String>

RSS Feed Function

Use this function to access an RSS feed which lists when secondary analysis jobs complete or fail.

  • URL: /rss
  • Method: GET
  • Returns: An RSS XML file.

User Service

The User Service includes functions used to manage users, roles and passwords.

List Users Function

Use this function to list users on the system. (Administrators only)

  • URL: /users
  • Method: GET or POST
  • Parameters: options=SearchOptions (Only sortOrder, sortBy and columnNames are supported.)
  • Returns: PagedList<User>

User Details Function

Use this function to obtain information about a specific user. (Administrators only)

  • URL: /users
  • Method: GET
  • Parameters: userName=string
  • Returns: User

Save User Function

Use this function to save changes made to a user. (Administrators only)

  • URL: /users/{userName}
  • Method: POST or PUT
  • Parameters:
    • userName=string
    • data=User
  • Returns: A notice message object.

Delete User Function

Use this function to delete a user from the system. (Administrators only)

  • URL: /users/{userName}
  • Method: DELETE
  • Parameters: userName=string
  • Returns: A notice message object.

Register User Function

Use this function to register a new user.

  • URL: /users/register
  • Method: POST
  • Parameters:
    • data=User (Required)
    • userName=string
    • email=string
    • password=string
    • confirmPassword=string
  • Returns: User

Change Password Function

Use this function to change a user’s password with a specified replacement password. This functionality is available to administrators for all passwords.

  • URL: /users/{userName}/change-password
  • Method: POST
  • Parameters:
    • data=User (Required)
    • userName=string
    • newPassword=string
    • password=string
    • confirmPassword=string
  • Returns: A notice message object.

Reset Password Function

Use this function to reset a user’s password. The user is then asked to change their password. (Administrators only)

  • URL: /users/{userName}/reset-password
  • Method: GET
  • Returns: A notice message object.

List User-Defined Fields Function

Use this function to obtain a list of user-defined fields. These fields are created using the RS Remote software. If a run specified a secondary analysis protocol, these fields (if defined) propagate throughout the secondary analysis pipeline.

  • URL: /custom-fields
  • Method: GET
  • Parameters: options=SearchOptions (*Only *sortOrder, sortBy and columnNames are supported.)
  • Returns: PagedList<CustomField>

List User-Defined Field Names Function

Use this function to obtain a list of the names of user-defined fields. These fields are created using the RS Remote software. If a run specified a secondary analysis protocol, these fields (if defined) propagate throughout the secondary analysis pipeline.

  • URL: /custom-fields/names
  • Method: GET
  • Returns: List<String>

Secondary Analysis Input Service

The Secondary Analysis Input Service includes functions used to manage the data associated with each SMRT Cell that is included in a secondary analysis job.

List Secondary Inputs Function

Use this function to obtain a list of secondary analysis input.

  • URL: /inputs
  • Method: GET or POST
  • Parameters: options=SearchOptions
  • Returns: PagedList<Input>

Secondary Input Details Function

Use this function to obtain details for a specfied secondary analysis input.

  • URL: /inputs
  • Method: GET
  • Parameters: id=int
  • Returns: Input
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/inputs
{
"page" : 1,
"records" : 1,
"total" : 1,
"rows" : [ {
"adapterSequence" : "ATCTCTCTCttttcctcctcctccgttgttgttgttGAGAGAGAT",
"bindingKitBarcode" : "000001001546011123111",
"bindingKitControl" : "Standard_v1",
"bindingKitExpirationDate" : "2011-12-31T00:00:00-0800",
...
} ]
}

Create Secondary Input Function

Use this function to create secondary analysis input.

  • URL: /inputs/create (Using POST), /inputs (Using PUT)
  • Method: POST, PUT
  • Parameters:
    • data=Input (Using POST)
    • Input (Using PUT)
  • Returns: PrimaryKey

Save Secondary Input Function

Use this function to save secondary analysis input.

  • URL: /inputs/{id}
  • Method: POST, PUT
  • Parameters:
    • data=Input
    • id=int
  • Returns: A notice message object.

Last Timestamp of Secondary Input Function

Use this function to obtain the time of the last secondary analysis input saved to the database.

  • URL: /inputs/last-timestamp
  • Method: GET
  • Returns: Date

Import Secondary Input Metadata Function

Use this function to import secondary analysis input.

  • URL: /inputs/import
  • Method: POST
  • Parameters: data=array of Collections from instrument
  • Returns: List<Input>

Scan for New Input Metadata Function

Use this function to scan for secondary analysis input.

  • URL: /inputs/scan
  • Method: POST
  • Parameters: paths=array of string
  • Returns: List<Input>
  • Example: curl -u administrator:administrator#1 -d 'paths=["/data/smrta/smrtanalysis/common/inputs_dropbox"]' http://secondary_host:8088/smrtportal/api/inputs/scan
  • Python® code example:
import os
import logging
import urllib
import urllib2
import json
import base64

log = logging.getLogger(__name__)

class DefaultProgressErrorHandler(urllib2.HTTPDefaultErrorHandler):
    def http_error_default(self, req, fp, code, msg, headers):
        result = urllib2.HTTPError(req.get_full_url(), code, msg, headers, fp)
        result.status = code
        return result

def request_to_string(request):
    "for debugging"
    buffer = []
    buffer.append('Method: %s' % request.get_method())
    buffer.append('Host: %s' % request.get_host())
    buffer.append('Selector: %s' % request.get_selector())
    buffer.append('Data: %s' % request.get_data())
    return os.linesep.join(buffer)

def scan():
    url = 'http://localhost:8080/smrtportal/api/inputs/scan'
    #You'd want to use something like this: /opt/testdata/LIMS/2311013/0002
    #Having trouble getting this to work with > 1 path. How to pass multiple form params of same name to urllib2?
    c_path = '/data/smrta/smrtanalysis/common/inputs_dropbox'
    scan_data = urllib.urlencode({'paths[]': c_path } )
    request = urllib2.Request(url, data=scan_data)
    request.add_header('User-Agent', 'admin-user')
    key = 'Basic %s' % (base64.b64encode("administrator:administrator#1"))
    request.add_header('Authorization', key)
    opener = urllib2.build_opener(DefaultProgressErrorHandler())
    response = opener.open(request)
    #response.read() - in this case - returns a list of len == to number of paths you're passing as data
    retList = json.loads( response.read() ) 
    return retList[0]['idValue']

def saveJob(inputId):
    url = 'http://localhost:8080/smrtportal/api/jobs/create'
    job = {
        'name':'test_job',
        'createdBy':'admin',
        'protocolName':'RS_Filter_Only.1',
        'groupNames':['all'],
        'inputIds':[inputId]
    }
    job_data = urllib.urlencode( {'data': json.dumps(job)  } )

    request = urllib2.Request(url, data=job_data)
    print request_to_string(request)

    request.add_header('User-Agent', 'admin-user')
    key = 'Basic %s' % (base64.b64encode("administrator:administrator#1"))
    request.add_header('Authorization', key)

    opener = urllib2.build_opener(DefaultProgressErrorHandler())
    response = opener.open(request)
    ret = json.loads( response.read() )
    return ret['idValue']

def startJob(jobId):
    url = 'http://localhost:8080/smrtportal/api/jobs/{i}/start'.format(i=jobId)

    #This is a GET
    request = urllib2.Request(url)
    print request_to_string(request)

    request.add_header('User-Agent', 'admin-user')
    key = 'Basic %s' % (base64.b64encode("administrator:administrator#1"))
    request.add_header('Authorization', key)

    opener = urllib2.build_opener(DefaultProgressErrorHandler())
    response = opener.open(request)
    ret = json.loads( response.read() )
    print( ret )

def test():
    inputId = scan()
    print( 'Scanned inputId = %s' % inputId ) 
    jobId = saveJob(inputId)
    print( 'jobId = %s' % jobId )     
    startJob(jobId)

Delete Secondary Input Function

Use this function to delete specified secondary analysis input. (Scientists and administrators only)

  • URL: /inputs/{id}
  • Method: DELETE
  • Parameters: id=int
  • Returns: A notice message object.

Compatibility Function

Use this function to return information specifying whether the SMRT Cell inputs for the job are compatible.

  • URL: /inputs/compatibility
  • Method: GET
  • Parameters: ids=[array of ids]
  • Returns: JSON object specifying whether or not the inputs are compatible.

Groups Function

Use this function to update group information for SMRT Cell inputs.

  • URL: /inputs/{INPUT_ID}/groups
  • Method: POST
  • Parameters: data=[name of groups]. Example: data=”[‘grp1’, ‘grp2’]”
  • Returns: A notice message object.

Cleanup Function

Use this function to delete any input that is unassociated with a job and has an invalid or empty collectionPathUri. This is useful for cleaning up duplicate SMRT Cells located at different paths. When you scan and import SMRT Cells from SMRT Portal and the same SMRT Cell ID already exists, the existing path is updated to the new location. No duplicate entries are created. (Scientists and administrators only)

  • URL: /inputs/{INPUT_ID}/cleanup
  • Method: DELETE
  • Returns: A notice message object that includes the list of deleted input IDs.

Jobs Service

The Jobs Service includes functions used to manage secondary analysis jobs.

List Jobs Function

Use this function to obtain a list of all secondary analysis jobs.

  • URL: /jobs
  • Method: GET or POST
  • Parameters: options=SearchOptions
  • Returns: PagedList<Job>
  • Example:
curl -d 'options={"filters":{"rules":[{"field":"createdBy","op":"eq","data":"AutomationSystem"},{"field":"jobId","op":"lt","data":"30000"}],"groupOp":"and"},"columnNames":["jobId"],"rows":"0"}' http://pssc1:8080/smrtportal/api/jobs
{
"page" : 1,
"records" : 57,
"total" : 1,
"rows" : [ {
"jobId" : 26392
}, {
"jobId" : 26360
}, {
"jobId" : 26359
}, {
...
}]
}

List Jobs by Status Function

Use this function to obtain a list of secondary analysis jobs, based on their job status.

  • URL: /jobs/by-status/{jobStatus}
  • Method: GET or POST
  • Parameters: options=SearchOptions
  • Returns: PagedList<Job>
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/by-status/Completed
{
"page" : 1,
"records" : 25,
"total" : 3,
"rows" : [ {
"automated" : true,
"collectionProtocol" : "Standard Seq v2",
...
} ]
}

List Jobs By Protocol Function

Use this function to list the currently open secondary analysis jobs, based on a specified protocol.

  • URL: /jobs/by-protocol/{protocol}
  • Method: GET or POST
  • Parameters: protocol=string, options=SearchOptions, jobStatus= status code such as NotStarted.
  • Returns: PagedList<Job>
  • Example:
curl -d 'jobStatus=Completed' http://pssc1:8080/smrtportal/api/jobs/by-protocol/RS_resequencing.1
{
"page" : 1,
"records" : 1,
"total" : 1,
"rows" : [ {
"automated" : false,
...
"whenStarted" : null
} ]
}

Job Details Function

Use this function to display details of a secondary analysis job.

  • URL: /jobs/{id} or /jobs/by-name/{name}
  • Method: GET
  • Parameters: id=int, name=string
  • Returns: Job
  • Examples:
By ID:
curl -u administrator:administrator#1 http://pssc1:8080/smrtportal/api/jobs/016437
{
"jobId" : 16437,
"protocolName" : "RS_Site_Acceptance_Test.1",
"referenceSequenceName" : "lambda",
"jobStatus" : "Completed",
...
"whenModified" : "2012-01-31T09:12:48-0800",
"modifiedBy" : null
}
By Name:
curl -u administrator:administrator#1 http://pssc1:8080/smrtportal/api/jobs/by-name/2311084_0002
{
"jobId" : 16437,
"protocolName" : "RS_Site_Acceptance_Test.1",
"referenceSequenceName" : "lambda",
"jobStatus" : "Completed",
...
"whenModified" : "2012-01-31T09:12:48-0800",
"modifiedBy" : null
}

Create Job Function

Use this function to create a new secondary analysis job.

  • URL: /jobs/create (Using POST), /jobs (Using PUT)
  • Method: POST or PUT
  • Parameters: data=Job (Using POST), job (Using PUT). In both cases, the name must be unique, and CreatedBy must be non-null.
  • Returns: PrimaryKey
  • Example:
curl -u administrator:administrator#1 -d 'data={"name":"DemoJobName", "createdBy":"testuser", "description":"demo job", "protocolName":"RS_Resequencing.1", "groupNames":["all"], "inputIds":["78807"]}' http://pssc1:8080/smrtportal/api/jobs/create
{
"idValue" : 16478,
"idProperty" : "jobId"
}

Save Job Function

Use this function to save a secondary analysis job.

  • URL: /jobs/{id}
  • Method: POST, PUT
  • Parameters: id=int, data=Job
  • Returns: A notice message object.

Delete Job Function

Use this function to delete a secondary analysis job. (Administrators only)

  • URL: /jobs/{id}
  • Method: DELETE
  • Parameters: id=int
  • Returns: A notice message object.
  • Example:
curl -u "administrator:administrator#1" -X DELETE http://pssc1:8080/smrtportal/api/jobs/16478
{
"success" : true,
"message" : "Job 16478 has been permanently deleted"
}

Archive Job Function

Use this function to archive a secondary analysis job. (Administrators only)

  • URL: /jobs/{id}/archive (Using GET), /jobs/archive (Using POST)
  • Method: GET, POST
  • Parameters: id=int (Using GET), ids=int[] (Using POST)
  • Returns: A notice message object.
  • Example:
curl -u administrator:administrator#1 -d 'ids=[16437,16438]' http://pssc1:8080/smrtportal/api/jobs/archive
{
"success" : true,
"message" : "Archived 2 jobs."
}

Restore Archived Job Function

Use this function to restore a secondary analysis job that was archived. (Administrators only)

  • URL: /jobs/{id}/restore (Using GET), /jobs/restore (Using POST)
  • Method: GET, POST
  • Parameters: id=int (Using GET), ids=int[] (Using POST)
  • Returns: A notice message object.
  • Example:
curl -u administrator:administrator#1 -d 'ids=[16437,16438]' http://pssc1:8080/smrtportal/api/jobs/restore
{
"success" : true,
"message" : "Restored 2 jobs."
}

Get Job Metrics Function

Use this function to retrieve metrics for a secondary analysis jobs.

  • URL: /jobs/{id}/metrics2
  • Method: GET
  • Parameter: id=int
  • Returns: List<String>

Get Job Protocol Function

Use this function to return the protocol used by a secondary analysis job.

  • URL: /jobs/{id}/protocol
  • Method: GET
  • Parameters: id=int
  • Returns: Protocol XML document
  • Example:
curl http://pssc1:8080/smrtportal/api/jobss/16437/protocol
<smrtpipeSettings>
<protocol version="1.3.0" id="RS_Site_Acceptance_Test.1" editable="false">
<param name="name" label="Protocol Name" editable="false">
...
<fileName>settings.xml</fileName>
</smrtpipeSettings>

You can also return a protocol as a json object by specifying a header item:

curl --verbose  -H "accept:application/json" 
http://localhost:8080/smrtportal/api/jobs/16454/protocol

Set Job Protocol Function

Use this function to specify the protocol used by a secondary analysis job.

  • URL: /jobs/{id}/protocol
  • Method: POST
  • Parameters: id=int, data=Xml(escaped) This is a function used for transmission from a web browser, such as the Javascript escape function.
  • Returns: A notice message object.

You can also return a protocol as a json object by specifying a header item:

curl --verbose  -H "accept:application/json" 
http://localhost:8080/smrtportal/api/jobs/16454/protocol

Get Job Inputs Function

Use this function to return information about the SMRT Cell data used for a secondary analysis job.

  • URL: /jobs/{id}/inputs
  • Method: GET
  • Parameters: id=int
  • Returns: PagedList<Input>

Start Job Function

Use this function to start a secondary analysis job.

  • URL: /jobs/{id}/start
  • Method: GET
  • Parameters: id=int
  • Returns: JobStatus
  • Example:
curl -u administrator:administrator#1 http://pssc1:8080/smrtportal/api/jobs/16479/start
{
"jobStatusId" : 1775,
"jobId" : 16479,
"code" : "Submitted",
"jobStage" : null,
"moduleName" : null,
"percentComplete" : 0,
"message" : "Job submitted",
"name" : null,
"description" : null,
"whenCreated" : null,
"createdBy" : null,
"whenModified" : null,
"modifiedBy" : null
}

Get Job Status Function

Use this function to obtain the status of a secondary analysis job.

  • URL: /jobs/{id}/status
  • Method: GET
  • Parameters: id=int
  • Returns: JobStatus
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16479/status
{
"jobStatusId" : 1780,
"jobId" : 16479,
"code" : "In Progress",
"jobStage" : "Filtering",
"moduleName" : "P_FilterReports/adapterRpt",
"percentComplete" : 100,
"message" : "task://016479/P_FilterReports/adapterRpt complete",
"name" : null,
"description" : null,
"whenCreated" : "2012-02-03T17:38:06-0800",
"createdBy" : "smrtpipe",
"whenModified" : "2012-02-03T17:38:06-0800",
"modifiedBy" : null
}

Update Job Status Function

Use this function to modify the status of a secondary analysis job. (Scientists and administrators only)

  • URL: /jobs/{id}/status
  • Method: POST, PUT
  • Parameters: id=int, progress=JobStatus
  • Returns: PrimaryKey
  • Example:
curl -u administrator:administrator#1 -d 'progress={"code":"Failed"}' http://pssc1:8080/smrtportal/api/jobs/16471/status
{
"success" : true,
"message" : "Job status updated"
}

Job History Function

Use this function to obtain the history of a secondary analysis job.

  • URL: /jobs/{id}/history
  • Method: GET
  • Parameters: id=int
  • Returns: List<JobStatus>
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/history
[ {
"jobStatusId" : 1773,
"jobId" : 16437,
"code" : "Completed",
"jobStage" : null,
"moduleName" : null,
"percentComplete" : 0,
"message" : null,
"name" : null,
"description" : null,
"whenCreated" : "2012-02-03T17:13:31-0800",
"createdBy" : null,
"whenModified" : "2012-02-03T17:13:31-0800",
"modifiedBy" : null
}, {
...
}]

Job Log Function

Use this function to obtain the log for a secondary analysis job.

  • URL: /jobs/{id}/log
  • Method: GET
  • Parameters: id=int
  • Returns: Text file
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/log
[INFO] 2012-01-30 23:52:41,437 [SmrtPipeContext 139] Configuration override for PROGRESS_URL: Old: --> New: http://pssc1:8080/smrtportal/api
[INFO] 2012-01-30 23:52:41,437 [SmrtPipeContext 150] Changing working directory to /tmp/tmpTKPKi4
...
[INFO] 2012-01-31 00:35:10,443 [SmrtPipeContext 362] Removed 2 temporary directories
[INFO] 2012-01-31 00:35:10,450 [SmrtPipeContext 365] Removed 1 temporary files
[INFO] 2012-01-31 00:35:10,450 [SmrtPipeMain 394] Successfully exiting smrtpipe
***

Analysis Table of Content Function

Use this function to returns a JSON object listing the reports and data files that were generated for a secondary analysis job. This function is used primarily for SMRT Portal to display the report and data links in the View Data/Job Details page.

  • URL: /jobs/{id}/contents
  • Method: GET
  • Parameters: id=int
  • Returns: JSON object listing contents.
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/contents
{
"reportGroups" : [ {
"name" : "General",
"members" : [ {
"group" : "General",
"title" : "Workflow",
"links" : [ {
"path" : "workflow/Workflow.summary.html",
"format" : "text/html"
...
}

Job Analysis File Function

Use this function to obtain any specified file that was generated during a secondary analysis job.

  • URL: /jobs/{id}/contents/{file} or /jobs/{id}/contents/{dir}/{file}
  • Method: GET
  • Parameters: id=int, file=filename, dir=directory
  • Returns: Data file, report XML, image, and so on.
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/contents/results/overview.xml
<?xml version="1.0" encoding="UTF-8"?>
<report>
<layout onecolumn="true"/>
<title>General Attribute Report</title>
<attributes>
<attribute id="n_smrt_cells" name="# of SMRT Cells" value="1">1</attribute>
<attribute id="n_movies" name="# of Movies" value="2">2</attribute>
</attributes>
</report>

Mark Job Complete Function

Use this function to specify that a job using more than one SMRT Cell is complete.

  • URL: /jobs/{id}/complete
  • Method: GET
  • Returns: A notice message object.
  • Example:
http://pssc1:8080/smrtportal/api/jobs/16477/complete
{
"jobStatusId" : 1844,
"jobId" : 16477,
"code" : "Submitted",
"jobStage" : null,
"moduleName" : null,
"percentComplete" : 0,
"message" : "Job submitted",
"name" : null,
"description" : null,
"whenCreated" : null,
"createdBy" : null,
"whenModified" : null,
"modifiedBy" : null
}

List Jobs in Dropbox Function

Use this function to list the jobs located in the Job Import Dropbox.

  • URL: /jobs/dropbox-paths
  • Method: GET
  • Returns: List<String>
  • Example:
curl -u administrator:administrator#1 http://pssc1:8080/smrtportal/api/jobs/dropbox-paths
[ "999991" ]

Import Job Function

Use this function to import a job located in the Job Import Dropbox.

  • URL: /jobs/import
  • Method: POST
  • Parameters: paths=array of strings
  • Returns: List<PrimaryKey>
  • Example:
curl -u administrator:administrator#1 -d 'paths=["/opt/smrtanalysis/common/jobs_dropbox/035169"]' http://pssc1:8080/smrtportal/api/jobs/import
[ {
"idValue" : 16480,
"idProperty" : "jobId"
} ]

Job Last Heartbeat Function

Use this function to find out if a job is still alive.

  • URL: /jobs/{id}/status/heartbeat
  • Method: GET
  • Returns: A notice message object.
  • Example:
curl -u administrator:administrator#1 -d "data={'lastHeartbeat':'2011-06-20T00:50:20-0700'}" http://pssc1:8080/smrtportal/api/jobs/016471/status/heartbeat
{
"success" : true,
"message" : "Job lastHeartbeat status updated"
}

Job Raw-Read Function

Use this function to download a data file generated by a job.

  • URL: /jobs/{id}/raw-reads
  • Method: GET
  • Returns: Data file, report XML, image, and so on.
  • Example:
curl http://pssc1:8080/smrtportal/api/jobs/16437/raw-reads?format=fasta

Protocol Service

The Protocol Service includes functions that you use to manage the protocols used by secondary analysis jobs.

List Protocols Function

Use this function to obtain all the active and inactive protocols in the system.

  • URL: /protocols
  • Method: GET
  • Returns: PagedList<Protocol>

Protocol Details Function

Use this function to obtain details about a protocol.

  • URL: /protocols/{id}
  • Method: GET
  • Parameters: id=string
  • Returns: An XML protocol file.

You can also return a protocol as a json object by specifying a header item:

curl --verbose  -H "accept:application/json" 
http://localhost:8080/smrtportal/api/jobs/16454/protocol

Update Protocol Function

Use this function to update a protocol.

  • URL: /protocols/{id}
  • Method: POST, PUT
  • Parameters: id=string, data=Xml
  • Returns: A notice message object.

You can also update a protocol as a json object by specifying a header item:

curl --verbose  -H "accept:application/json" 
http://localhost:8080/smrtportal/api/jobs/16454/protocol

Delete Protocol Function

Use this function to permanently delete a protocol.

  • URL: /protocols/{id}
  • Method: DELETE
  • Parameters: id=string
  • Returns: A notice message object.

Sample Sheet Service

The Sample Sheet Service includes a function to validate a specified sample sheet.

Validate Sample Sheet Function

  • URL: /sample-sheets/validate
  • Method: POST
  • Parameters: sampleSheet=SampleSheet
  • Returns: A notice message object.

Settings Service

The Settings Service includes functions that you use to manage the SMTP host, send test email, manage instrument URIs, and manage the file input paths where SMRT Portal looks for secondary analysis input, reference sequences, and jobs to import.

Check Free Disk Space Function

Use this function to check how much free space resides on the disk containing the jobs directory, by default located at /opt/smrtanalysis/common/jobs.

  • URL: /settings/free-space
  • Method: GET
  • Returns: Floating point value between 0 and 1, representing the fraction of disk space that is free.

Get Job Dropbox Function

Use this function to obtain the location of the dropbox where SMRT Portal looks for jobs to import.

  • URL: /settings/job-dropbox
  • Method: GET
  • Returns: The path for the job dropbox directory.

Set Job Dropbox Function

Use this function to specify the location of the Job Import Dropbox where SMRT Portal looks for jobs to import.

  • URL: /settings/job-dropbox
  • Method: POST, PUT
  • Parameters: path=string
  • Returns: A notice message object.

Get Reference Sequence Dropbox Function

Use this function to obtain the location of the Reference Sequence Dropbox where SMRT Portal looks for reference sequences.

  • URL: /settings/reference-dropbox
  • Method: GET
  • Returns: The path for the reference sequence dropbox directory.

Set Reference Sequence Dropbox Function

Use this function to specify the location of the Reference Sequence Dropbox where SMRT Portal looks for reference sequences.

  • URL: /settings/reference-dropbox
  • Method: POST, PUT
  • Parameters: path=string
  • Returns: A notice message object.

Get SMTP Host Function

Use this function to obtain the name of the current SMTP host.

  • URL: /settings/smtp-host
  • Method: GET
  • Returns: The host name.

Set SMTP Host Function

Use this function to specify the name of the SMTP host to use.

  • URL: /settings/smtp-host
  • Method: POST, PUT
  • Parameters: host=string
  • Returns: A notice message object.

Send Test Email Function

Use this function to send a test email to the administrator, using the specified SMTP Host.

  • URL: /settings/smtp-host/test
  • Method: GET
  • Parameters: host=string
  • Returns: A notice message object, then sends an email to the administrator.

Get Input Paths Function

Use this function to obtain the file input paths where SMRT Portal looks for secondary analysis input.

  • URL: /settings/input-paths
  • Method: GET
  • Returns: List<String>

Add Input Paths Function

Use this function to add file input paths where SMRT Portal looks for secondary analysis input.

  • URL: /settings/input-paths
  • Method: POST, PUT
  • Parameters: data=array of paths
  • Returns: A notice message object.

Remove Input Paths Function

Use this function to remove file input paths where SMRT Portal looks for secondary analysis input.

  • URL: /settings/input-paths
  • Method: DELETE
  • Parameters: data=array of paths
  • Returns: A notice message object.

Validate Path for use in pbids Function

Use this function to validate the URI (Universal Resource Identifier) path that specifies where the primary analysis data is stored. You specify the path using the RS Remote software; the path uses the pbids format.

  • URL: /settings/validate-path
  • Method: POST
  • Parameters: path=string
  • Returns: A notice message object.

Get Instrument URIs Function

Use this function to obtain the URI (Universal Resource Identifier) that specifies the location of the PacBio instrument(s) running the Instrument Control Web Services.

  • URL: /settings/instrument-uris
  • Method: GET
  • Returns: List<String>

Add Instrument URIs Function

Use this function to specify the URI (Universal Resource Identifier) that specifies the location of the PacBio instrument(s) running the Instrument Control Web Services.

  • URL: /settings/instrument-uris
  • Method: POST, PUT
  • Parameters: data=array of URIs
  • Returns: A notice message object.

Remove Instrument URIs Function

Use this function to remove the URI (Universal Resource Identifier) that specifies the location of the PacBio instrument(s) running the Instrument Control Web Services.

  • URL: /settings/instrument-uris
  • Method: DELETE
  • Parameters: data=array of URIs
  • Returns: A notice message object.

Test Instrument URIs Function

Use this function to test the URI (Universal Resource Identifier) that specifies the location of the PacBio instrument(s) running the Instrument Control Web Services.

  • URL: settings/instrument-uris/test
  • Method: POST
  • Parameters: uri=instrument URI
  • Returns: A notice message object.

Check Anonymous UI Access Function

Use this function to check whether users have read-only access to SMRT Portal without logging in. (Users must still log in to create or modify jobs.)

  • URL: /settings/restrict-web-access
  • Method: GET
  • Returns: True/False

Set Anonymous UI Access Function

Use this function to specify whether users have read-only access to SMRT Portal without logging in. (Users must still log in to create or modify jobs.)

  • URL: /settings/restrict-web-access
  • Method: POST, PUT
  • Parameters: value=true|false
  • Returns: A notice message object.

Check Anonymous Web Services Access Function

Use this function when your organization has written custom software to access SMRT Pipe, or integrate with a LIMS system. The function checks whether software can have access to certain web services methods without authentication.

  • URL: /settings/restrict-service-access
  • Method: GET
  • Returns: True/False

Set Anonymous Web Services Access Function

Use this function when your organization has written custom software to access SMRT Pipe, or integrate with a LIMS system. The function specifies whether software can have access to certain web services methods without authentication. (The software would supply the credentials programmatically.)

  • URL: /settings/restrict-service-access
  • Method: POST, PUT
  • Parameters: value=true|false
  • Returns: A notice message object.

Set Anonymous Web and UI Access Function

Use this function to specify 1) Whether a user has read-only access to SMRT Portal and 2) Whether software can use certain web services methods without authentication.

  • URL: /settings/restrict-access
  • Method: POST
  • Parameters: web=true|false, service=true|false
  • Returns: A notice message object.

Get Job Archive Directory Function

Use this function to obtain the path to the directory used to store archived jobs.

  • URL: /settings/job-archive
  • Method: GET
  • Returns: The path for the job archive directory.

Set Job Archive Directory Path Function

Use this function to set the path to the directory used to store archived jobs.

  • URL: /settings/job-archive
  • Method: POST, PUT
  • Parameters: path=string
  • Returns: A notice message object.

Set Enable Wizards

Use this function to enable or disable the Protocol Selector wizard.

  • URL: /settings/enable-wizards
  • Method: GET
  • Returns: A notice message object.

Group Service

The Group Service includes functions that you use to manage groups of SMRT Portal users.

Create Group Function

Use this function to create a new group of users. (Administrators only)

  • URL: /groups/create (Using POST), /groups (Using PUT)
  • Method: POST or PUT
  • Parameters: data=Group (Using POST), group (Using PUT). In both cases, the name must be unique, and CreatedBy must be non-null.
  • Returns: PrimaryKey

Save Group Function

Use this function to save a specified group of users. (Administrators only)

  • URL: /groups/{id}
  • Method: POST or PUT
  • Parameters: id=int, data=group
  • Returns: A notice message object.

Delete Group Function

Use this function to delete a specified group of users. (Administrators only)

  • URL: /groups/{id}
  • Method: DELETE
  • Parameters: id=int
  • Returns: A notice message object.

List Group Names Function

Use this function to get a list of the names of groups of users on the system. (Administrators only)

  • URL: /groups/names
  • Method: GET
  • Returns: List<String>

List Groups Function

Use this function to return information about the groups of users available on the system. (Administrators only)

  • URL: /groups
  • Method: GET, POST
  • Parameters: options=SearchOptions
  • Returns: PagedList<Group>

For Research Use Only. Not for use in diagnostic procedures. © Copyright 2010 - 2014, 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.
P/N 000-999-643-06