API Beginner Guide

API Introduction

Any operation from the Emedgene graphical user interface (GUI) can also be performed by using the Emedgene API.

Following are some basic examples of how to use Emedgene API with Python.

For instructions on using the API with other programming languages, please refer to their respective documentation.

Prerequisites

• An installed copy of Python (https://www.python.org/)

• The Python package installer, pip (https://pip.pypa.io/)

• The requests library installed (run pip install requests)

Authentication

In order to perform a secure session with Emedgene API servers you should first accomplish the authentication phase and retrieve the bearer token. The bearer token is further required to perform API requests on associated resources without extra identification. The token is valid for a predefined time. Once the bearer token is not valid, you will need to revalidate the token and accomplish the authentication phase again.

There are two ways to get your authentication token for your user before executing API calls:

Emedgene Domain users - https://<hostname>.emedgene.com

To generate the authorization token, use your username and password as follows:

route_login_platform = 'https://<hostname>.emedgene.com/api/auth/v2/api_login/'
payload = {"username": user_name, "password": password}
response = requests.post(route_login_platform, json=payload)
access_token = response.json().get('access_token')
token_type = response.json().get('token_type')
print(f'{token_type.capitalize()} {access_token}')

This is your Bearer token that will be used for the following API requests.

Illumina Domain users - https://<hostname>.emg.illumina.com

For Illumina domain users there are two options to authenticate your user and retrieve the Bearer token.

1. Illumina credentials - use your username and password

route_login_platform = 'https://<hostname>.emg.illumina.com/api/auth/v2/api_login/'
payload = {"username": user_name, "password": password}
response = requests.post(route_login_platform, json=payload)
access_token = response.json().get('access_token')
token_type = response.json().get('token_type')
bearer_token = f'{token_type.capitalize()} {access_token}'
print(bearer_token)

1. Using your API Key to generate the authentication token. To generate an API Key take a look API Key Generating. Copy your API Key to the code below instead of 'my-api-key'.

import base64

api_key = 'my-api-key'
route_token_platform = 'https://<hostname>.login.illumina.com/platform-services-manager/Token'

# Prepare the API Key
client_id_apikey = f'emedgene:{api_key}'
client_id_apikey_bytes = client_id_apikey.encode("ascii")
client_id_apikey_base64_bytes_encoded = base64.b64encode(client_id_apikey_bytes)
client_id_decoded = client_id_apikey_base64_bytes_encoded.decode("ascii")

# Use the API Key
headers = {
    'Authorization': f'Basic {client_id_decoded}'
}
params = {
    "audience": "emedgene", 
    "grant_type": "api_key"
}
response = requests.post(route_token_platform, params=params, headers=headers)

access_token = response.json().get('access_token')
token_type = response.json().get('token_type')
bearer_token = f'{token_type.capitalize()} {access_token}'
print(bearer_token)

Either of these options will produce your Bearer token that will be used for the following API requests.

API Reference

The different API commands can be found at https://<hostname>.emedgene.com/api/apidoc/swagger or https://<hostname>.emg.illumina.com/api/apidoc/swagger

It is useful to explore possible APIs and get an overview of the available parameters.

Creating Python requests from curl

The examples in the API Reference page use curl (Client URL), while Python uses requests.

In order to get the curl command:

1. Find the endpoint you want to use on the API Reference page.

2. Select Try it out.

3. Enter the necessary parameters.

4. Select Execute.

5. Copy the resulting curl command.

Let's break down the parts of a curl command:

curl -X 'POST' 'https://<hostname>.emg.illumina.com/api/some/command/path/' 
   -H 'Authorization': 'Bearer your-auth-token'  
   -d '{"DataName": "DataValue", ...}' 

-X specifies the request method to use when communicating with the HTTP server. By default, curl performs a GET request, but you can use the -X option to set a different method, such as POST, PUT, DELETE, etc.

-H allows you to pass custom headers to the server.

-d is used to send data in a POST request to the server. This option implies using the POST method.

To translate a POST command to a Python request:

import requests
url = 'https://<hostname>.emg.illumina.com/api/some/command/path'
headers = {
    'Authorization': 'Bearer your-auth-token',
}
data = {
    'DataName': 'DataValue',
}
response = requests.post(url=url, headers=headers, json=data)

Translating a GET command would be similar:

import requests
url = 'https://<hostname>.emg.illumina.com/api/some/command/path'
headers = {
    'Authorization': 'Bearer your-auth-token',
}
response = requests.get(url=url, headers=headers)

Examples

In the examples below, <hostname>.emedgene.com and <hostname>.emg.illumina.com are used indifferently.

The following examples will build the requests step-by-step, allowing you to execute them individually to understand their functionality, using the output of one request as the input for the next.

You can also use the GUI to obtain all the parameters or record them after executing the individual API calls in this section. Then, use these values to construct your final API call.

Get list of cases

This example can be used as a simple way to verify your connection.

import requests

headers = {
    'Authorization': 'Bearer your-auth-token',
}

# Store the API response in a response variable
response = requests.get('https://<hostname>.emg.illumina.com/api/test', headers=headers)

Checking the response

To validate the API request was completed successfully, check the HTTP response code.

HTTP 200 means the API call was successful. Learn more about HTTP response code here.

# Display the response status code
print(f"Response status code: {response.status_code}")

# Display the data from the request
print(response.json().get("hits"))

In order to pretty-print the JSON response and view it in a formatted way:

import json

# Print JSON data in readable format with indentation and sorting.
print(json.dumps(response.json().get("hits"), indent=3, sort_keys=True))

Tip: when returning lists (like lists of cases) Emedgene API uses pagination. It is possible to get the next items from the list using from and size, shown below.

import requests

params = {
    'from': 5,    # get the 6th case
    'size': 10    # get 10 cases
}

headers = {
    'Authorization': 'Bearer your-auth-token',
}

# Store the API response in a response variable
response = requests.get('https://<hostname>.emg.illumina.com/api/test', params=params, headers=headers)

Get list of storage providers

Now that we are able to retrieve information with the API, let's continue by using it for a more practical request like retrieving the list of storage providers your user can access files from.

Your storage provider holds the sample files accessible for creating samples in a case.

url = 'https://<hostname>.emg.illumina.com/api/storage'
headers = {
    'Authorization': 'Bearer your-auth-token',
}
response = requests.get(url, headers=headers)
print(response.json().get("hits"))

Create new case

To create a new case, multiple parameters need to be defined such as samples, the relationship between samples, phenotypes, genes and more. All the required details can be found in the API Reference page under /api/cases/v2/cases .

Once the complete JSON defining the case details is complete, the case can be created as follows:

url = 'https://<hostname>.emedgene.com/api/cases/v2/cases'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
data = {...}
response = requests.post(url, json=data, headers=headers)

Once the case was created successfully, the response code expected is HTTP 201.

Use the case name to retrieve information about the case.

case_name = response.json().get("name")

Check the status of a case

In order to know if the case has completed successfully, check the status as follows:

url = f'https://<hostname>.emg.illumina.com/api/test/{case_name}?test_fields=status'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
response = requests.get(url, headers=headers)
print(response.json())

Get more information about a case

To get more information about a case, use the same API call as above without any test_fields

url = f'https://<hostname>.emg.illumina.com/api/test/{case_name}'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
response = requests.get(url, headers=headers)
print(response.json())

The response can be used to find which test fields are of interest and use them in the next API calls:

url = f'https://<hostname>.emg.illumina.com/api/test/{case_name}?test_fields=status&test_fields=participants&test_fields=patients'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
response = requests.get(url, headers=headers)
print(response.json())

Get candidates of completed case

To retrieve the candidate variants of the completed case:

url = f'https://<hostname>.emg.illumina.com/api/candidates/{case_name}'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
response = requests.get(url, headers=headers)
print(response.json().get("hits"))

To retrieve candidate variants of the completed case with details such as transcript data, pathogenicity, ACMG tags and more:

url = f'https://<hostname>.emg.illumina.com/api/test/{case_name}/export'
headers = {
    'Authorization': 'Bearer your-auth-token' 
}
response = requests.get(url, headers=headers)
print(response.json().get("hits"))