4 Apr 2019

• Documentation extended with better description of the supported genetic file format.

16 Oct 2018

• Added operation for genotype file uploading using time-limited secure URLs generated on-the-fly

Contact API support directly via email (api-support@lifenome.com) or report a bug or feature request on the Trello board (Trello account must be created and permission must be granted to the board by the API support team. The board itself contains information on how to use the issue tracker).

Lifenome API is the REST web service which exposes functionalities for the following resources:

• Profile: represents single person with genetic data and optional phenotype data (e.g. email address, names or gender).
• Trait: represents genetically determined characteristic for which assessments can be computed (e.g. Overweight potential). Access to trait results is charged, but there might be a set of free traits assigned to the client.
• Trait assessment: represents assessment results based on the provided genetic data for the given trait (e.g. Overweight potential trait is elevated for the Profile X)

• Production server: https://api.lifenome.com

OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

This section lists one possible usage scenario for the Lifenome API with the demonstration of the complete workflow - starting from the authentication procedure and finishing with the reading of the trait assessments for the newly created profile. In order to read the genetic trait assessments for the existing genetic data, API client needs to:

1. Obtain the access token
2. Create profile
3. Upload genetic data
4. (Optional) Get list of traits with pricing info assigned to the client
5. Get annotated list of traits available for the profile
6. Get trait assessments for free traits (if any)
7. Computing the assessment data for basic (non-free) traits
8. Reading the trait assessments

Steps 1-8. are described in the following sections.

First, authentication token must be obtained by calling the authentication endpoint:

  curl --url "https://lifenome.auth0.com/oauth/token" \
       --request POST \
       --header 'content-type: application/json' \
       --data '{"client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "audience": "https://api.lifenome.com/profiles",  "grant_type": "client_credentials"}'

Also, token can be extracted into environment variable using e.g. jq tool:

  export ACCESS_TOKEN=$(curl --url 'https://lifenome.auth0.com/oauth/token' --request POST --header 'content-type: application/json'   --data '{"grant_type":"client_credentials","client_id": "<CLIENT_ID>","client_secret": "<CLIENT_SECRET>","audience": "https://api.lifenome.com/profiles"}' | jq -r '.access_token')

Fetched access token must be included into the Authorization header for every subsequent request to protected resources of the API.

Note that <CLIENT_ID> and <CLIENT_SECRET> can be obtained by contacting the API support.

Every genetic file that will be analyzed must be connected to a Profile resource. Before uploading of the genetic file and obtaining the assessment data, profile must be created:

  curl --url "https://api.lifenome.com/profiles/" \
       --request POST \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json" \
       --data '{"first_name": "John", "last_name": "Doe", "age": 32}'

  {
    "id": "<PROFILE_ID>",
    "email": "",
    "first_name": "John",
    "last_name": "Doe",
    "gender": 0,
    "age": 32,
    "ethnicity": 0
  }

Successful operation will return status code 201 Created and the added profile will be assigned with the unique profile id string (<PROFILE_ID>) that will be used for accessing operations on the profile.

Using the profile id, the profile that was just created will be available at the profile endpoint:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/" \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "id": "<PROFILE_ID>",
    "email": "",
    "first_name": "John",
    "last_name": "Doe",
    "gender": 0,
    "age": 32,
    "ethnicity": 0
  }

Also, added profile will be listed at the profile collection endpoint:

  curl --url "https://api.lifenome.com/profiles/" \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
      {
           "id": "<PROFILE_ID>",
           "email": "",
           "first_name": "John",
           "last_name": "Doe",
           "gender": 0,
           "age": 32,
           "ethnicity": 0
       }
  ]

Genetic files are uploaded directly to Lifenome storage servers by first fetching the time-limited secure storage URL for the corresponding profile (<PROFILE_ID>) using the endpoint:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/genotype/upload/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "url": "<UPLOAD_URL>"
  }

Genetic file itself (<FILE_PATH>) can be uploaded directly to the provided <UPLOAD_URL>:

  curl -X PUT -H 'content-type: text/plain' --data-binary @<FILE_PATH> "<UPLOAD_URL>"

Please note the method PUT used for the upload (POST will not work).

When the file upload completes, Lifenome backend will automatically start processing the file. Results will be available for retrieval once all the calculations are completed. Currently, the only way to test if the asynchronous automatic processing finished is to poll the Profile Traits endpoint (see sections 5. and 6. in this chapter). Also, file processing can be initiated using the synchronous call that will block the caller using the operation:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/genotype/upload/" \
       --request POST \
       --header "Authorization: Bearer ${TOKEN}" \
       --header "Content-Type: application/json"

Lifenome API calculates genetic assessments for the selected set of Traits. Every trait is represented with the unique trait code. List of all traits assigned to the given API client, with included pricing type, is exposed at the endpoint:

  curl --url "https://api.lifenome.com/traits/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait" : {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
      },
      "type": "basic"
    },          
    {
      "trait" : {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
      },
      "type": "basic"
    },
    {
      "trait" : {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
      },
      "type": "free"
    },
    {
      "trait" : {
        "code": "trait_code_4",
        "name": "Trait 4",
        "overview": "<p>This is the description of Trait 4.</p>",
        "connotation": "good"
      },
      "type": "basic"
    },
    ...
  ]

The endpoint returns list of Trait objects with trait code and additional trait metadata. All traits obtained from this endpoint will be considered for computation for the given API client.

In general, access to trait assessments is charged according to the existing pricing models. However, free traits can be assigned to clients. Each trait in the previous response includes trait type field which defines the pricing model. In the example, access to all traits will be charged, with the exception of Trait 3. Please use this endpoint to obtain list of free traits defined for your API client.

Some traits may not be available for the selected profile, regardless of the pricing model defined by type attribute. For example, maybe genetic data is incomplete and required genetic markers are missing for the particular trait. In order to get annotated list of traits that are analyzed and connected to a certain profile, Profile Traits endpoint must be called:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/traits/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait": {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
        },
      "status": "available"
    },
    {
      "trait": {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
        },
      "status": "available"
    },
    {
      "trait": {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
        },
      "status": "computed"
    },
    {
      "trait": {
        "code": "trait_code_4",
        "name": "Trait 4",
        "overview": "<p>This is the description of Trait 4.</p>",
        "connotation": "good"
        },
      "status": "unavailable"
    },
    ...
  ]

Response contains list of trait objects with trait codes and statuses. Detailed description of statuses is available here. If the Profile Traits endpoint returns empty response, this means that the genetic file is missing or the file upload/processing is still in progress.

Profile traits endpoint can be used for quick access to all free trait assessments in a single call, if there are any free traits defined for the client. If score query parameter is provided for the GET method on the Profile traits endpoint, the response will include assessment data for the computed traits (free traits are always automatically computed, unless it is not possible to compute them, e.g. incomplete genetic data):

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/traits/?score" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait": {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
      },
      "status": "computed",
      "assessment_level": 1,
      "recommendations": "...",
      "percentile": 45.0,
      "snps": ["rs12345"]
    }
  ]

In order to read assessments for the selected set of (non-free) traits, assessment computation needs to be initiated. Note that computation can only be initiated for the traits that have available value for the status attribute. If the trait assessments cannot be computed for a given profile, those traits will have status=unavailable (e.g. incomplete genetic data). Moreover, if there are free traits assigned to your client, those traits will be automatically computed (status=computed) and trait assessments can be retrieved without initiating the computation (Trait 3 in the previous example).

Assessment computation for the set of traits can be initiated with the call:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/traits/" \
       --request POST \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json" \
       --data '{"trait_codes": ["trait_code_1", "trait_code_2"]}'

  [
    {
      "trait": {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
        },
      "status": "computed",
      "assessment_level": 0,
      "recommendations": "...",
      "percentile": 15.0,
      "snps": ["rs978739"]
    },
    {
      "trait": {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
        },
      "status": "computed",
      "assessment_level": 0,
      "recommendations": "...",
      "percentile": 5.0,
      "snps": ["rs1175549"]
    }
  ]

Response already includes list of trait codes with statuses and computed assessments. Request can include arbitrary number of trait codes, but only those traits with status=available will be computed. Note that statuses of the computed traits will be changed to computed.

Assessment for the previously computed selected profile trait can be fetched anytime using the known <PROFILE_ID> and <TRAIT_CODE> with the call:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "trait": {
      "code": "trait_code_1",
      "name": "Trait 1",
      "overview": "<p>This is the description of Trait 1.</p>",
      "connotation": "risky"
    },
    "status": "computed",
    "assessment_level": 0,
    "recommendations": "...",
    "percentile": 15.0,
    "snps": ["rs978739"]
  }

Additionally, computation of the assessments can also be initiated anytime for a single trait using the same endpoint (with PUT operation) and the response will include full computed assessment data:

  curl --url "https://api.lifenome.com/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
       --request PUT \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"
  {
    "trait": {
      "code": "trait_code_x",
      "name": "Trait x",
      "overview": "<p>This is the description of Trait x.</p>",
      "connotation": "risky"
    },
    "status": "computed",
    "assessment_level": 0,
    "recommendations": "...",
    "percentile": 45.0,
    "snps": ["rs12345"]
  }

When creating genotype profiles using the API, client needs to submit files that contain genetic data. Genetic data is provided in the simple textual file, usually with .txt or .csv extensions, but the API also supports upload of compressed archives (.zip, .gz and .tar.gz).

Genetic data stored inside textual files is divided into header and genetic data. All header lines are prefixed with # character:

  # header line 1
  # header line 2
  # ...

  genetic data line 1
  genetic data line 2
  ...

Lines that contain genetic data (SNPs) are formatted according to following rule:

  RSID<sep>CHR[optional]<sep>POS[optional]<sep>A1<sep>A2

• RSID is the required SNP identifier and it must begin with prefix rs.

• CHR is the optional chromosome identification. Allowed values are numbers 1-23 or characters X, Y. Optionally, the value can be prefixed with chr.

• POS is the optional position within the chromosome (integer).

• A1 is the required first allele for the given SNP (one of ATCG-)

• A2 is the required second allele for the given SNP (one of ATCG-)

Note that <sep> can be any valid separator (space, comma, tab). Also, separator can be repeated any number of times. Additionally, separator between alleles is optional.

Described file format is designed to support parsing of textual files from most popular data providers. For instance, samples from 23andme, ancestry.com or FamilyTreeDNA adhere to the presented data format and, as such, can be submitted directly to the API, without any extra file content manipulation. In addition to files fetched from the mentioned services, any textual file that is formatted according to the previously defined rules will be accepted by the API.

The following section presents some of the most common file formats supported by the API. The samples are taken from the popular genetic data providers. Note that some header lines are omitted from the examples.

23andMe

  # This data file generated by 23andMe ...
  # rsid    chromosome    position    genotype
  rs1       1             734462      AA
  ...

Ancestry.com

  #AncestryDNA raw data download ...
  rsid    chromosome    position    allele1    allele2
  rs1     1             82154       A          G
  ...

FamilyTreeDNA

  # name,chromosome,position,allele1,allele2
  rs1,17,7579472,G,G
  ...

Profile resource

Profile resources are used to store person's metadata and person's genotype data which are used to compute genetic assessments of various traits.

Following endpoints expose operations on Profile resources:

• Basic profile management operations:
  • Create new profile
  • List existing profiles
  • Update existing profile metadata (complete and partial update are supported)
  • Delete profile

Profile Traits resources are child resources of the Profile resource. Following endpoints expose operations on Profile Traits resources:

• Basic profile trait management operations:
  • List traits available for given profile
  • Initiate assessment data for a set of profile traits
  • Fetch the assessment data for a single trait
  • Initiate assessment data computation for a single trait

Lifenome's fast and secure genotype storage is powered by Google Cloud infrastructure. Genetic files are uploaded directly to storage servers using time-limited secure URLs generated on-the-fly resulting in secure and scalable solution for genetic file uploading. Upon completion of the file upload, Lifenome backend will automatically start processing the uploaded file. For security reasons, time-limited secure URLs provide access to storage for only limited amount of time (currently 3 minutes). When the received URL expires, storage API will return appropriate response and client must ask for a new URL. The API currently supports only textual files (e.g. .txt, .csv, .tsv) with content type text/plain.

Traits configured for authenticated API client.