Documentation Overview¶
SolveBio is a cloud-based operating system for molecular information that enables cross-disciplinary R&D groups to use complex multi-omics data from disparate sources to find biomarkers, stratify populations, and design clinical trials. SolveBio’s mapping technology transforms structured data into biomedical entities such as variants, genes, patients, samples, compounds, and phenotypes. Harmonized datasets are indexed and maintained on SolveBio and can be easily delivered to end-users via APIs and applications built upon them.
SolveBio provides many options for developers looking to enhance existing applications or build new ones quickly. Bioinformatics skills are not required but can be very helpful.
-
Vaults
Secure virtual filesystem for organizing and sharing files and datasets.
-
Datasets
Flexible and scalable data structure for real-time querying and analysis.
-
Expressions
Python-based language for transforming and extending datasets.
-
Applications
Build and deploy OAuth2-secured applications on top of SolveBio.
Getting Started¶
To get started, choose one of the available client libraries and work through the Dataset Quickstart. There are also a few example scripts available.
Authentication¶
API Keys have been deprecated in favor of Personal Access Tokens
SolveBio is phasing out API keys and the API will begin blocking them in Q1 2021. Please migrate to Personal Access Tokens by following the instructions below for Python and R.
Clients can authenticate with Personal Access Tokens (recommended) or API keys (deprecated). Create a new Personal Access Token by clicking "Generate New Token" on the Personal Access Tokens page. Alternatively, to retrieve your API key, click the "Show API Key" button on the API Key settings page. Without valid credentials, API endpoints may return 404 Not Found, 403 Forbidden, or 401 Not Authorized.
Authenticating with Python¶
Please upgrade your Python client
SolveBio recommends using the latest version of the Python client (v2.12.0 or higher).
To upgrade, run pip install --upgrade solvebio
In order to avoid keeping your tokens stored in Python scripts, the SolveBio Python client uses a stored credentials file located at ~/.solvebio/credentials.
Run the following command in your terminal to automatically create or update the credentials file:
# Clear your existing credentials $ solvebio logout # Replace "TOKEN" with the Personal Access Token copied from the SolveBio website # Replace "DOMAIN" with your account's subdomain (i.e. your company name) $ solvebio login --access-token TOKEN --api-host https://DOMAIN.api.solvebio.com # If you are using an API Key, run the following command, replacing KEY with your API Key $ solvebio login --api-key KEY --api-host https://DOMAIN.api.solvebio.com
Once your credentials are stored, use the login() function to automatically load them in a script:
1 2 3 4 | import solvebio # Loads your token from the credentials file solvebio.login() |
Alternatively, you may store your Personal Access Token in the $SOLVEBIO_ACCESS_TOKEN environment variable, or your API Key in the $SOLVEBIO_API_KEY environment variable. This will be automatically loaded by the Python client, even if login() is not called.
Authenticating with R¶
The SolveBio R library looks for the $SOLVEBIO_ACCESS_TOKEN (for Personal Access Tokens) or $SOLVEBIO_API_KEY (for API Keys) environment variables.
Add the following to your ~/.Rprofile file in your home directory to set the environment variable. Replace TOKEN with the Personal Access Token copied from the SolveBio website, and DOMAIN with your subdomain (i.e. your company name):
Sys.setenv(SOLVEBIO_ACCESS_TOKEN="TOKEN") Sys.setenv(SOLVEBIO_API_HOST="https://DOMAIN.api.solvebio.com")
Alternatively, if you are using an API Key use the following but replace KEY with your API Key and DOMAIN with your subdomain (i.e. your company name):
Sys.setenv(SOLVEBIO_API_KEY="KEY") Sys.setenv(SOLVEBIO_API_HOST="https://DOMAIN.api.solvebio.com")
When writing R scripts, load your token from the environment variable using the login() function:
1 2 3 4 | library(solvebio) # Load your token from the environment variable solvebio::login() |
Using a custom API endpoint¶
The default SolveBio API endpoint (https://api.solvebio.com) may be disabled for your organization (for example if access is restricted by IP address). You will need to configure all scripts and apps to use the custom endpoint. Your "domain" is the sub-domain used to access the SolveBio website (typically your organization's name in lowercase). For example, if you usually visit https://acme.solvebio.com, your domain is "acme".
For Python scripts and Dash apps:
- If you use the credentials file (
~/.solvebio/credentials), modify the line withmachine api.solvebio.comto bemachine domain.api.solvebio.com - In your scripts, if you use the
solvebio.login()function, modify it to be:solvebio.login(api_host="https://domain.api.solvebio.com") - If you use environment variables for authentication, change
$SOLVEBIO_API_HOSTtohttps://domain.api.solvebio.com
For R scripts and Shiny apps:
- If you use the
~/.RProfileto store your environment variables, ensure it contains:Sys.setenv(SOLVEBIO_API_HOST="https://domain.api.solvebio.com") - In your scripts, if you use the
solvebio::login()function, modify it to be:solvebio::login(api_host="https://domain.api.solvebio.com") - If you use environment variables for authentication, change
$SOLVEBIO_API_HOSTtohttps://domain.api.solvebio.com
If you have any questions, please contact SolveBio Support and we'll do our best to assist you.
Testing your credentials¶
There are a few ways to test your credentials. If you are using the Python client, you can run solvebio whoami from the command line:
$ solvebio whoami
# You are logged-in to the "***" domain as ****@****.com with role member.
Within a block of python code:
# Login solvebio.login() # Get the current User user = solvebio.User.retrieve() print(user.email)
Within a block of R code:
# Load your credentials from $SOLVEBIO_API_KEY solvebio::login() # Get current User User.retrieve()$email
You can test a Personal Access Token using the Authorization: Bearer header:
curl --header "Authorization: Bearer <TOKEN>" https://api.solvebio.com # {"detail": "Your API key is valid. Welcome to the SolveBio API!"}
You may also specifying it in the access_token query parameter:
curl "https://api.solvebio.com?access_token=<TOKEN>" # {"detail": "Your API key is valid. Welcome to the SolveBio API!"}
Can't find what you're looking for? Contact SolveBio Support and we'll do our best to assist you.
Not a developer?¶
Building applications using SolveBio requires some development skills. You can always use SolveBio through its intuitive and friendly web interface: sign in here.
We're here to help!¶
We're always happy to help out with code or any questions you may have. Feel free to submit a ticket at any time or email support@solvebio.com to get in touch.