Transnetyx Developer Portal

Getting Started

Introduction

Transnetyx provides web-based API interaction with its most popular products and services. This portal serves as the primary developer hub, with links to the end-point documentation pages and product details. Transnetyx implements its APIs using standard REST paradigms unless otherwise stated in the endpoint documentation.

API Access

The security mechanism of the Transnetyx APIs are based on OAuth2 authorization flow. Developers register for a free account and then request tokens appropriate to the products or services that they wish to integrate with. Access to the Transnetyx API platform is provided as a value-add service to partners and 3rd party vendors. By accessing the APIs, you agree to the terms of service of the respective product.

Developer Account

To obtain access to the developer dashboard, a developer must first Register for a Transnetyx Account. This account provides access to the suite of Transnetyx products and services. After the user account is created, when you navigate to the developer portal, you will be prompted to enter your Organization and Contact information. If you are an existing customer of Transnetyx, please select the toggle button that says In-house/Institutional API Developer. You will be prompted to enter and select the Organization(s) from the suggestion box. If you are a 3rd party API Developer that is working with one of our customers, please leave the toggle button un-selected. Once the API Org details are saved, a client secret will be automatically generated for your API Org and can be viewed on the Refresh Tokens page.

Requesting Tokens

The next step for the developer is to work with a customer/researcher and request access to their data via API. Our customers have the ability to grant access to their data to API Developers/Vendors using the API Options widget on the Accounts page. They can also revoke access at any time. Once access is granted, the developer can view the customer name and the refresh token on the Refresh Tokens page. The refresh tokens are long-lived and can be exchanged for an access token using the refresh_token grant type. The Access Token can be used as Bearer token to call APIs using the Authorization header.

Authorization and access flow

*Developer's app (client) calls Transnetyx Auth Provider's "/oauth/token" endpoint with a valid "client_secret", a user "refresh_token".
*Transnetyx Auth Provider creates an Access Token based on the provided Refresh Token and sends it back to the client.
The Client calls the API with Access Token.
Auth Provider validates Access Token.
Auth Provider allows or denies access for the HTTP call. Denial returns a 403 (access token invalid or expired) response to the client.
If access is allowed, the API receives the HTTP Request and processes it.
The API sends its response back to the client.

* Steps 1 and 2 will only have to be done once per user. If making multiple calls back to the API for a single user, then the API can just be called directly over and over using just the Access Token (until the access token expires, then a new access token needs to be obtained via steps 1 and 2).

HTTP (formatting added for readability)

POST /oauth/token HTTP/1.1
Host: https://api.transnetyx.com/accounts
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=<client_id>     //provided by Transnetyx
&client_secret=<client_secret>     //generated by developer using developer portal
&refresh_token=<refresh_token>     //provided by the customer

Please note that API endpoint, grant_type, client_id and client_secret values are subject to change and should be configurable in the client application

Product Overview

QuickOrder

Transnetyx QuickOrder is the primary molecular diagnostics services ordering portal. The current version of the software (v1.x) provides customers with an end-to-end order placement and results retrieval system. The application provides these facilities for each of the diagnostic products, as listed below.

Automated Genotyping

The Automated Genotyping product is the cornerstone of Transnetyx services and provides customers with the ability to have their genetic samples tested against a reference strain using quantitative polymerase chain reaction genotyping (qPCR).

Learn more about Automated Genotyping: https://www.transnetyx.com/why-outsource

Genetic Monitoring

Genetic Monitoring from Transnetyx allows customers to gauge the relative genetic similarity between their samples and reference mouse lines.

Learn More about Genetic Monitoring: https://www.transnetyx.com/monitoring

Microbiome Analysis

Microbiome Analysis from Transnetyx provides a genetic survey of the gut microorganisms present in animal colonies by isolating DNA profiles via fecal samples.

Learn more about Microbiome Analysis: https://www.transnetyx.com/microbiome

API Usage

Conventions

Unless otherwise specified in the endpoint documentation, Transnetyx APIs are structured to conform to RESTful patterns. They will typically expose endpoints that rely on HTTP verb invocation (GET, POST, PUT, etc.) and standard HTTP response codes. Request and Response objects conform to JSON object structures, with application/json as the Content-Type header, unless otherwise specified. Some endpoints may also provide an alternate XML response format when requested. See the endpoint documentation to determine when an XML response structure is available.

Transnetyx uses the Swagger documentation package as the standard endpoint documentation system. Learn more about Swagger here: https://swagger.io/

For information on how to get started using REST API resource, visit: https://www.restapitutorial.com/resources.html

Data Sharing Opt-In Requirements

Transnetyx respects the privacy and data security requirements of our customers. In accordance with our customer privacy policy, data is provided via the API endpoints through a voluntary opt-in system. It is the responsibility of the developer/partner organization to solicit access to our shared customer data. Transnetyx may, at its sole discretion, prevent access to customer data for security or privacy concerns irrespective of their Opt-In status.

When customer data is unreachable with a response code of 403 - Forbidden, either the user or Transnetyx has prevented access to the resources requested. Contact the account owner to ensure that they have agreed to data sharing via the API system.

Environments

Transnetyx provides access to Staging and QA instances of product APIs for use during development and integration testing. Please be aware that the data in these systems are subject to being changed, deleted, refreshed or updated without prior notice and are provided as-is with no warranty.

Test environments require a separate registration and token request process. Production API tokens will not authenticate in the test environments, and vice versa.

Security

Transnetyx provides partners with access to customer data via cryptographic API keys. The API platforms monitor and in some cases record activity over the API systems. As detailed in the Terms of Service, it is the responsibility of customer and partner organization to secure their token at all times, to revoke tokens if it is deemed to have been compromised, and to inform Transnetyx if suspected abuse or breaches have occurred that could compromise the security or data integrity of any Transnetyx system.

Transnetyx reserves the right to revoke API key access, throttle requests, or deactivate accounts that behave in suspicious or abusive ways without notice.

Transnetyx® API Resources