Introduction

Fabric Genomics provides an API based on the HTTPS protocol, using HTTP requests (GET, POST, PUT and DELETE) to securely transmit variation data, launch analyses and retrieve finished report data.

Authorization

Every request must authenticate against our database of API Keys, providing the login and password according to the HTTP basic access authentication method (see Wikipedia - basic access). Please contact support to have them generate an API Key for your application. An API Key is tied to a specific Fabric user, referred to as the API User hereon. Any email messages generated when using the Fabric API are sent to the API User.

Fabric Genomics stores passwords in a one-way encrypted hash according to industry standard security procedures. Passwords cannot be recovered, but we can issue a new API key upon request.

The Fabric API uses SSL-encrypted HTTP for its protocol, via the normal port for secure HTTP, 443. Attempts to query the server with non-encrypted HTTP request on port 80 (ie. http://api.fabricgenomics.com instead of https://api.fabricgenomics.com) will return a 302 Redirect HTTP response, with no response body provided.

GET Methods and Query Parameters

All GET methods of the API accept a custom header to transfer query parameters in the body of the request.

The name of the custom header is X-fg-safe-params.

This allows clients to make parameterized requests that can't accidentally leak PHI when stored either as a bookmark or to other persistent media. The parameter must be prepared as a conventional URI query, that is key1=value1&key2=value2 etc. Keys can be repeated. The string must be first encoded as UTF8, then Percent Encoded to ensure that only USASCII characters are part of the header value. For example, using python 2.7, do the following: 
              # -*- coding: utf-8 -*-
              import urllib
              params = {"param1": "value1", "param2": u"āēīūčģķļņšž"}
              ...
              request.headers["X-fg-safe-params"] = urllib.urlencode(params)
              ...
The server pre-processes each GET request and, if the header is found, decodes the field content and adds the key value pairs as regular parameters, ensuring that the server behaves as if the parameter were part of the request URI.

Errors

Most invalid requests (e.g. for invalid parameter values) return an HTTP status of 400, 404 or 422; authentication errors return an HTTP status of 401 or 403.

Dates

All dates and times are returned in PST.

Example Code

Please refer to the links below for some end-to-end examples making use of the Fabric API:
Python Examples
Bash Examples

Use Cases

Uploading Genomes

Once you obtain an API Key you can start uploading your samples to Fabric for annotation, analysis and clinical report generation. API Keys are associated with a single Workspace (a group of Projects and Users), and genomes must be uploaded to specific projects within that Workspace. You may either use an existing project, or leverage the API to create a new project for this purpose. To create a Project use a POST request against the Create Project endpoint. You will need to specify a Project name and optionally a description and a parameter to indicate how the project should be shared with existing and future members of your workspace. Projects are identified by a numeric ID. This ID is necessary when uploading, listing and otherwise accessing genomes and reports.

To upload a VCF file use the Upload endpoint, including the entirety of the file as the body of the request. The assembly version must be hg19 (internally we handle GRCh37 and hg19 interchangeably).

The Fabric API accepts VCF 4.0+ (view format here) preferably containing a single sample column.

The system assigns a unique ID to all uploaded genomes. These IDs are used to identify the genome within Fabric. External IDs are an alternate method to identify and find genomes within the Fabric API. Fabric does not enforce uniqueness of the external ID.

Multi-sample VCF’s can be uploaded, however in this case the ID returned by the upload call cannot be used to reference the individual genomes comprising the original file. The Fabric VCF parser accepts quality and read depth data in a variety of formats. Please refer to the Fabric Enterprise user guide for more information, or contact support for specific questions.

Upon successful parsing, the uploaded genome is queued for annotation by the Fabric Enterprise Pipeline. Panel and exome VCFs usually annotate within minutes, while full genomes can take longer.

If any genome fails to annotate, the system will send an email notification to the API User as well as the Fabric Genomics Support Team.

Relevant example Python scripts: Genome Workflows

Launching Clinical Reports

A clinical report combines genome variant data with other information relevant to the sample being tested, such as patient information and quality control data.

Once all genomes are successfully uploaded, the API can be used to submit them for clinical reporting. It is also possible to create a clinical report that does not yet reference any genomes, and then attach the genomes at a later point in time using the Update Clinical Report endpoint.

Both family and panel reports can be launched using the Create Report endpoint.

For a family report (which can involve up to 4 family members in addition to the proband) the system will first ensure all requisite genomes are fully annotated, then run pertinent VAAST Solo and Trio analyses. The clinical report's submission for processing is contingent on all of its genomes and analyses running successfully to completion.

For a panel report, the system will submit the report for processing as soon as its proband genome's annotation finishes.

If any of the genomes fail to annotate, or if there are issues with the VAAST runs, the system will send an email notification to the API User as well as the Fabric Genomics Support Team.

Once a clinical report has been created, the Post Patient Fields endpoint can be used to upload custom patient information.

To check a clinical report’s status, use the Get One Clinical Report endpoint and supply the ID of the report in question. Alternately, query all clinical reports by report status to at the Get Many Clinical Reports endpoint. In addition, reports can be found by accession, external ID or genome ID, also using the above endpoint.

Relevant example Python scripts: Clinical Report Workflows

Exporting Data

Once a clinical report has been completed and is ready to review, its variants can be interpreted using the Fabric Enterprise UI, but can also be exported at any time using the API using the Get Variants endpoint. Variants of interest can be exported in JSON, CSV, or VCF format. The scoring information for variants can be exported using the Get Scored Variants endpoint. Scoring criteria, scoring status, and the scoring audit log can be exported in JSON format. After external validation has been performed, the variants’ status can be set using the Update Variant endpoint.

For auditing purposes, or to integrate with an external LIM system, it can be useful to have access to all information associated with the clinical report itself. To extract a full JSON representation of a clinical report the Get One Clinical Report endpoint will be of use.

The PDF output associated with an approved clinical report can also be exported using the Get Final PDF endpoint and stored locally. A preview PDF document can be exported from a clinical report in any other state using the Get PDF Preview endpoint.

Relevant example Python scripts: Clinical Report Workflows