Hello World! BUILD Module¶
This notebook shows how to interact with the BUILD API. First it shows the accessing the API through the TeselaGen's Python API Client, and then it shows the same but with a general purpose requests library.
Requirements:
- Python 3.9+
- TeselaGen's Python Client 0.4.4+
We start by making some imports
from pathlib import Path
import platform
import json
print(f"Python version: {platform.python_version()}")
from IPython.core.display import display
from IPython.core.display import HTML
import teselagen
print(f"TeselaGen's Python Client version: {teselagen.__version__}")
from teselagen.api import TeselaGenClient
from teselagen.utils.plot_tools import plot_plasmid_features
from teselagen.utils.plot_tools import RenderJSON
# Define the host url address to be used across this notebook
HOST_URL = "https://demo-single.teselagen.com"
1. Python API Client (Alternative 1)¶
Here it is described how to connect to API by using Python API Client.
Make login into the platform. You should get "Connection Accepted" printed below.
# Connect to your teselagen instance by passing it as the 'host_url' argument of TeselaGenClient(host_url=host_url)
client = TeselaGenClient(host_url=HOST_URL)
# client = TeselaGenClient()
client.login()
client.select_laboratory(lab_name="TeselaGen")
Exploring Samples¶
The get_samples method can be used for exploring Samples. The gqlFilterparameter can be used to filter the query by different criteria, as shown in the following examples:
gqlFilter: str = json.dumps({"name": "Pool8-Isolate63"})
samples = client.build.get_samples(gqlFilter=gqlFilter)
print(json.dumps(samples, indent=4))
Even "deep" references can be used as filters
gqlFilter: str = json.dumps({"taggedItems.tag.name": ["TagTest"]})# Also more than one simultaneous value can be used with a list, ex: ["TagTest1", "TagTest2"]
samples = client.build.get_samples(gqlFilter=gqlFilter)
print(json.dumps(samples, indent=4))
Retrieveing a specific plate¶
The endpoint for specific plates returns more information than the previous one. It also can be accessed via Python's Client and the id of the plate should be provided.
In this example we are use the id of one of the samples listed above
sample_id = samples[0]['id']
print(sample_id)
And now we get info about this particular register
sample_data = client.build.get_sample(sample_id=sample_id)
#print(json.dumps(sample_data, indent=4))
RenderJSON(sample_data)
This register contains a lot of detail. In this example it also stores information about DNA material. We can, for example, plot the related features:
sequence = sample_data['material']['polynucleotideMaterialSequence']
# Add "forward" field (this won't be requeried from teselagen >= 0.4.5)
features = map( lambda x: {**x, **{'forward': x['strand']==1}}, sequence['sequenceFeatures'])
# Plot features
_ = plot_plasmid_features(plasmid_length=sequence['size'],
features=[feat for feat in features if feat['end'] - feat['start'] > 100])
2. Generic Python requests (alternative 2)¶
If you prefer an alternative way to accessing the API, on this section we provide an example of BUILD API access through a general purpose http communication library (requests)
import requests
Login¶
Define connection variables
USERNAME = "****@teselagen.com" # Replace this with your username
PASSWORD = "*******" # Replace this with your password/api-key
Define a persistent session object that will be used for storing headers
session: requests.Session = requests.Session()
session.headers.update({'Content-Type': 'application/json', 'Accept': 'application/json'})
Login request. The next cell will just generate a token to be included in the headers
response: requests.Response = session.put(
url=f'{HOST_URL}/build/cli-api/public/auth',
json={
'username': USERNAME,
'password': PASSWORD,
'expiresIn': '1d',
},
)
response.raise_for_status() # Raise an error if a problem is found
# update session headers - TOKEN
session.headers.update(
{
'x-tg-cli-token': response.json()['token'] # TOKEN
},
)
del response
Also, a lab should be selected
# First we get the labs
response = session.get(
url=f'{HOST_URL}/test/cli-api/laboratories',
)
response.raise_for_status()
labs = {lab['name']:lab['id'] for lab in response.json()}
print(f"Available labs: {labs}")
# Now we select one
session.headers.update({'tg-active-lab-id': labs['TeselaGen']})
Let's take a look into the headers to be used:
print(session.headers)
We can now use those headers for calling any API endpoint, as in the following examples
Get Samples¶
# Set a filter parameter:
gqlFilter: str = json.dumps({"name": "Pool8-Isolate63"})
response = session.get(
url=f'{HOST_URL}/build/cli-api/samples?gqlFilter={gqlFilter}',
)
response.raise_for_status()
print(response.json()) # [{'id': str, 'name': str}, ... ]