⚠️ Under construction.
Get Started
Quickstart
Basic Sample Setup

Obtain access token

Access token obtained from Authorization API Create Token endpoint using your username and password:

curl --request POST \
  --url "https://se1.lifenome.com/platform-api/api/core-api/auth/token/" \
  --header "Content-Type: application/json" \
  --data '{"username": "'${USERNAME}'", "password": "'${PASSWORD}'"}'

Successful response will include two tokens:

{
  "refresh":"{REFRESH_TOKEN}",
  "access":"{ACCESS_TOKEN}"
}

For the rest of the tutorials, let's assume that obtained access token is stored in ACCESS_TOKEN environment variable.

Creating a Sample object

Basic Sample object is created by invoking Create Sample operation:

curl --request POST \
  --url https://se1.lifenome.com/platform-api/api/core-api/samples/ \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{}'

Successful response will include sample ID (id), creation timestamp (created_at) and an empty genotype field, which will be populated later:

{
  "id": "312235f8-...-c8b71648471d",
  "created_at": "2022-11-17T15:49:54.911283Z",
  "genotype": null
}

Created sample is uniquely identified with returned id (SAMPLE_ID) and it can be retrieved by supplying the same identifier using the Get Sample endpoint for getting sample details:

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

The response should be exactly the same as when the sample was created:

{
  "id": "312235f8-...-c8b71648471d",
  "created_at": "2022-11-17T15:49:54.911283Z",
  "genotype": null
}

Adding/updating attributes

Let's say that tenant supports weight and height numerical attributes in kilograms and centimeters, respectively. Those could be stored for a sample with the following request:

curl --request PUT \
  --url "https://se1.lifenome.com/platform-api/api/core-api/samples/${SAMPLE_ID}/attributes/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"weight": 70, "height": 170}'

Note: Each PUT request will overwrite any existing values. Partial updates of sample attributes are supported with PATCH method, e.g.:

curl --request PATCH \
  --url "https://se1.lifenome.com/platform-api/api/core-api/samples/${SAMPLE_ID}/attributes/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"height": 175}'

Reading attributes

Stored attributes are available for a GET request on the same endpoint:

curl --request GET \
  --url "https://se1.lifenome.com/platform-api/api/core-api/samples/${SAMPLE_ID}/attributes/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Response will include previously stored data:

{
  "height":175,
  "weight":70
}

Providing genotype data for the sample

Genotype data files can be imported into LifeNome Platform in several ways as described in Genotype Docs

One way to provide genetic data for a sample is to upload genotype file (Upload File Docs) using a two-step process:

  1. Fetch temporarily signed upload URL
  2. Upload file to temporarily signed URL

This procedure is described in detail in Providing genetic files. Here, we quickly list all the required calls for uploading new genotype file.

First, client must get a temporarily signed URL for the local genotype file stored in LOCAL_PATH which will be uploaded to DEST_PATH.

curl --request GET \
  --url "https://se1.lifenome.com/platform-api/api/core-api/files/upload/${DEST_PATH}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Successful response will return generated upload URL (UPLOAD_URL) in the upload_url field, which can then be used in the second step, where genotype file is actually uploaded:

curl --request PUT \
  --url ${UPLOAD_URL} \
  --data-binary @${LOCAL_PATH}

And final step is to create genotype object that will use the uploaded file as a data source. This is done by invoking Create Genotype.

As described in the documentation, the client needs to provide source_uri property in a request body that points to previously uploaded genotype file stored in DEST_PATH.

Source URI is a property of a file stored in LifeNome Blob Storage and depends on Tenant storage configuration. In order to fetch source_uri of a file in LifeNome Blob Storage client needs to invoke Get File Details

curl --request GET \
  --url https://se1.lifenome.com/platform-api/api/core-api/files/${DEST_PATH}/ \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Response

{
    "name": "string",
    "object_uri": "string",
    "content_type": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "size": 0,
    "md5_hash": "string",
    "crc32c": "string",
    "etag": "string",
    "metadata": null
}
curl --request PUT \
  --url https://se1.lifenome.com/platform-api/api/core-api/samples/${SAMPLE_ID}/genotype/ \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data "{\"source_uri\": \"${OBJECT_URI}\"}"

After the genotype is created, genotype's processing status can be obtained by reading sample details in the genotype field:

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

Status is stored in the state field of the genotype object:

{
    "id": "312235f8-...-c8b71648471d",
    "created_at": "2022-11-17T15:49:54.911283Z",
    "genotype": {
      "assembly": "grch37",
      "source_uri": "gs://platform--staging/samples/312235f8-...-c8b71648471d/genotype/{GENOTYPE_FILENAME}",
      "state": "data-valid",
      "created_at": "2022-11-21T19:37:18.653792Z"
    }
}

Here, state transitioned to data-valid, which means that uploaded file is recognized as valid genotype.

Waiting for genotype processing

File analysis is an asynchronous process that is initiated automatically after uploading is completed, which means that the client doesn't initiate processing explicitly and client doesn't wait until the file processing is finished.

Once file processing is completed, genotype state will transition to processed:

{
    "id": "312235f8-...-c8b71648471d",
    "created_at": "2022-11-17T15:49:54.911283Z",
    "genotype": {
      "assembly": "grch37",
      "source_uri": "gs://platform--staging/samples/312235f8-...-c8b71648471d/genotype/{GENOTYPE_FILENAME}",
      "state": "processed",
      "created_at": "2022-11-21T19:37:18.653792Z"
    }
}

Reading processing results

Once genotype state has switched to processed, all DNA Traits Assessments will be available. DNA Traits assessments can be fetched from the List Traits:

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