File Service

The file service is responsible for the core file-related features in the LifeOmic Platform. It provides the ability for users to upload, store, and manage files. The file service is able to handle any format of file. It also allows you to view inline many of the file formats encountered in healthcare, including diagnostic reports, medical imagery, and genomic files. After the file service brings files into the platform, other LifeOmic Platform services can use and analyze the data.

For more details, see the File Service FAQ.

Getting Started with the File Service API

This guide walks you through using the file service for these basic operations:

• List Files
• Download Files
• Delete Files
• Upload Files
• Organize Files

For file service endpoint details, see API Reference Information. For authentication and other basic operations, see Getting Started.

List Files

GET https://api.us.lifeomic.com/v1/files is the API call to list all files for your LifeOmic account. To be more useful, we will refine this basic command with the project or datasetId parameter. To find the <project-id>, see Find the Project ID.

Project Specific Call Example

This cURL example uses the datasetId parameter to specify the project:

curl --location 'https://api.us.lifeomic.com/v1/files?datasetId=<project-id>' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>'

Response to List Files Call

The files call returns a JSON response that lists the files and includes typical file data, such as name and size. The response also includes an lrn or LifeOmic Resource Name. This is a unique resource identifier that allows the platform to always reference the file resource. The identifier remains constant and is not affected by circumstances that can impair a typical HTTP URL resource reference. For more details, see Resource Names (LRNs).

Response to List Files Call Example with nextPageToken

This response highlights the lrn and nextPageToken values.

{
    "items": [
      .....
        {
            "id": "bfdf7716-1088-4021-80b5-ab4badacd081",
            "name": "initial_lab_report copy.pdf",
            "datasetId": "ebe1618f-e474-4947-a6d2-18b19fac663a",
            "size": 138829,
            "contentType": "application/pdf",
            "lastModified": "2020-11-17T14:35:14.823Z",
            "userId": "lifeomic:lifeomic_joe.smith@company.com",
            "lrn": "lrn:xyz:xyz:lifeomic:file:bfdf7716-1088-4021-80b5-ab4badacd081"
        }
    ],
    "links": {
        "self": "/v1/files?datasetId=ebe1618f-e474-4947-a6d2-18b19fac663a",
        "next": "/v1/files?nextPageToken=eyJpZCI6eyJTIjoibGlmZW9taWM6YmZkZjc3MTYtMTA4OC00MDIxLTgwYjUtYWI0YmFkYWNkMDgxIn0sImRhdGFzZXRJZCI6eyJTIjoibGlmZW9taWM6ZWJlMTYxOGYtZTQ3NC00OTQ3LWE2ZDItMThiMTlmYWM2NjNhIn0sInNvcnROYW1lIjp7IlMiOiJJTklUSUFMX0xBQl9SRVBPUlQgQ09QWS5QREYifX0=&datasetId=ebe1618f-e474-4947-a6d2-18b19fac663a"
    }
}

Parameters to Help Manage Large Numbers of Files

A project or account can have too many files to be listed in a simple response. The default number of files listed in a response is 25. If more files exist than can be contained in the response, a nextPageToken appears in the last line of the response, as highlighted in the JSON example above.

If you receive a nextPageToken in your response, the simplest way to display all the files is to increase the number of displayed files in the response by adding the query parameter pageSize <number> to your API call.

List Files Call with Page Size at 1000 Example

This cURL example sets the page size to display 1000 listings.

curl --location 'https://api.us.lifeomic.com/v1/files?pageSize=1000&datasetId=<project-id>' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>'

Response to List Files Call Example without nextPageToken

After increasing the page size, our response no longer contains a nextPageToken. This absence confirms that the response contains the last items in the file list.

{
    "items": [
        ....
        {
            "id": "e5852f3c-c0ae-4837-a053-3e527d27d048",
            "name": "test_patient_history_16.pdf",
            "datasetId": "ebe1618f-e474-4947-a6d2-18b19fac663a",
            "size": 138829,
            "contentType": "application/pdf",
            "lastModified": "2021-02-19T17:44:12.470Z",
            "userId": "company:joe.smith@company.com",
            "lrn": "lrn:xyz:xyz:company:file:e5852f3c-c0ae-4837-a053-3e527d27d048"
        }
    ],
    "links": {
        "self": "/v1/files?datasetId=ebe1618f-e474-4947-a6d2-18b19fac663a&pageSize=1000"
    }
}

If our response still contained a nextPageToken, we would need to employ the nextPageToken query parameter in our next call for additional results. This uses the nextPageToken <page-token> value from the previous call. You can continue to use the nextPageToken <page-token> value from the prior call until a nextPageToken is not listed in the results.

Example of List Files Call with nextPageToken

Here is a cURL example that uses the nextPageToken <page-token>. The <page-token> value is highlighted in the Response to List Files Call Example with nextPageToken.

curl --location 'https://api.us.lifeomic.com/v1/files?pageSize=1000&datasetId=<project-id>&nextPageToken<page-token>' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>'

Download Files

To download a file, you make another Get Files call. This time you add the file id from your earlier response and the include parameter with the downloadUrl value.

Example of Download a File Call

curl --location 'https://api.us.lifeomic.com/v1/files/<file-id>?include=downloadUrl' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>'

Response to Download a File Call

The response includes a downloadUrl with an http link to download the resource from a LifeOmic Amazon S3 bucket. You can download the file by pasting the URL in a browser. The link expires in 60 seconds.

{
    "id": "bfdf7716-1088-4021-80b5-ab4badacd081",
    "name": "initial_lab_report copy.pdf",
    "datasetId": "ebe1618f-e474-4947-a6d2-18b19fac663a",
    "size": 138829,
    "contentType": "application/pdf",
    "lastModified": "2020-11-17T14:35:14.823Z",
    "userId": "company:joe.smith@company.com",
    "lrn": "lrn:xyz:xyz:company:file:bfdf7716-1088-4021-80b5-ab4badacd081",
    "downloadUrl": "https://<presigned-url>"
}

Delete Files

To delete a file, you make a DELETE call and include the file id. A successful deletion returns a 204 (No Content) response with an empty response body.

Example of Delete a Listed File Call

curl --location --request DELETE 'https://api.us.lifeomic.com/v1/files/<file-id>' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>'

Upload Files

The file service uses Amazon S3 presigned object URLs to allow clients to upload files into the LifeOmic Platform. The presigned URL is configured for a specific bucket and object key to prevent the file from being stored in the wrong place.

Uploading files is a two call operation. The first call is a POST call for a response that contains the presigned URL. The second call is a PUT call to upload the file to the presigned URL.

POST Call to Upload a File

The POST call requires body data in the JSON format. If a file ID is not supplied by the user, a unique file ID is assigned with the response.

For Postman, click the Body tab and select the raw option and JSON. Paste the JSON key and value string in the text box.

Key	Value	Mandatory
name	file-name	Required
datasetId	lifeomic-project-id	Required
contentType	media-type	Optional
id	file-id	Optional

Example of Create a File POST Call

This example shows the JSON string after the data signifier for the body.

curl --location 'https://api.us.lifeomic.com/v1/files' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{"name":"test.json","datasetId":"ebe1618f-e474-4947-a6d2-18b19fac663a","contentType":"application/json"}'

Example of Create a File POST Response

The response to the POST call contains the presigned URL after the uploadUrl key.

{
    "id": "7c74a8e1-f118-4819-a2f7-04109a892c51",
    "name": "test.json",
    "datasetId": "ebe1618f-e474-4947-a6d2-18b19fac663a",
    "contentType": "application/json",
    "userId": "company:joe.smith.com",
    "uploadUrl": "https://<presigned-url>"
}

PUT Call to Upload a File

Make the PUT call that uploads the file data against the uploadUrl from the POST response. The required Amazon authentication parameters are also contained in the uploadUrl. The authentication expires in 60 seconds.

Include the file to be uploaded in the body request. For Postman, click the Body tab and select the binary option, then navigate to the file on your PC.

Example of Create a File PUT Call

curl --location --request PUT 'https://<presigned-url>' \
--header 'LifeOmic-Account: <account-id>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '@test.json'

Response to a Create a File PUT Call

A successful upload results in a 200 (OK) response message. You can confirm the file is stored in the LifeOmic Platform with a GET files call or click the Files tab of the LifeOmic Platform web app.

Organize Files

LifeOmic Platform files do not have a directory. But you can organize files in a similar fashion by using category names that function as folders. For example in your upload, you could name the file lab-report-1.pdf and lab-report-2.pdf as reports/lab-report-1.pdf and reports/lab-report-2.pdf. The LifeOmic Platform web app recognizes this scheme and displays a folder icon labeled reports that contains the files.

Other File Methods

In addition to the API, the LifeOmic Platform offers several alternative methods to upload and manage files. These include the LifeOmic Platform web app, SFTP, Amazon S3 to S3 Data Transfers, and the LifeOmic CLI. For more information, see the Files FAQ.