Real-Time Personalization (+RTP) API Guide

Real-Time Personalization^®  (+RTP) is a web service technology that enables software applications (apps) to provide context to data.

Context refers to an app having the ability to comprehend the uniqueness and individuality of each app user. In essence, the app is able to become cognizant of the app user as a unique individual.

Empowered by patent-pending Real-Time Personalization^®  technology, apps can now implicitly understand whether data is relevant to the user as the data is generated in real-time. And with an app’s cognizance of the user comes the ability for the app to provide a truly personalized experience.

Real-Time Personalization technology utilizes the most fundamental factor that makes each of us unique - our genes.

Sequencing.com’s Real-Time Personalization (+RTP) technology allows your app to obtain genetic-based information about the app user by making simple API calls to Sequencing.com.  The +RTP API enables your app to provide a personalized, gene-based user experience.

Adding +RTP to your app is easy. You don't need to know anything about genetics and you also don't need to learn any new coding languages.

Each +RTP API consists of:

• API request to Sequencing.com that includes a specific App Chain #
  • Click here to view all of the available App Chains
• Sequencing.com performs an ultra-rapid, real-time analysis of the app user's genes
• API response to your app with the result
  • Most responses are simple "Yes" or "No"

Through this approach, app developers can easily create personalized apps simply by utilizing Sequencing.com’s straightforward open API.

+RTP API plugins and code snippets are available for multiple languages and platforms and their number is constantly extended.

Example

1. App Chain88 determines whether the app user is likely to benefit from taking a Vitamin D supplement.
2. Your app will submit an API request for Chain88, Sequencing.com will perform ultra-rapid genetic analysis of the app user's genes.  
3. Your app will then receive the API response within a few milliseconds that will be one of the following:
   • yes
   • no
   • insufficient data
   • error
4. You code your app accordingly so that the user experience is tailored to the possible API responses.
5. Your app now provides a genetically tailored user experience to the app users genes!

Related

Developer Center

Plugins and Code Snippets

You can still easily integrate RTP into your own apps. This is because RTP technology was created so that it can be used by software developers regardless of their background or knowledge about genetics.

For those concerned about learning yet another new coding language, we hear you - we understand that you’re tired of learning one new language after the other. But fear not as we RTP translates genetic data into software code so that you don't have to learn anything new.

If you know how to use REST APIs then you can integrate RTP into your apps in a matter of minutes.

Search the list of App Chains

App Chains enable app developers without any experience or understanding of genetics to easily and quickly add genetically-tailored personalization to their apps.

Each +RTP API call is defined by a specific Chain#. When Sequencing.com receives a +RTP API call for a chain#, it knows (based on the chain#), which disease, trait or medication reaction to analyze. Sequencing.com performs the genetic analysis on the app user's genes and provides straightforward results as the API response.

Example of using an +RTP API App Chain

You have an idea for a new iPhone App that uses Apple’s Healthkit to help prevent heart attacks. You’re interested in adding personalization to this app but you don’t know anything about the genes that cause a heart attack.

Simply search the list of App Chains and you'll find Chain73 is for heart attack risk. Add Chain73 to your app (its easy with the Objective-C or Swift +RTP API Master Plugin) and indicate the action that will trigger your app to make this API call to Sequencing.com. For example, the action may be if app senses via GPS that the user walks into a restaurant that sells unhealthy food or if the app senses the user's heart rate exceeds 100 beats per minute. As the developer, you also code how your app responds to the possible responses for each App Chain.

When the user downloads your app from the App Store, she sees the option to 'Sign in with Sequencing.com.' The user already has her genetic data safely stored at Sequencing.com so she signs in with her Sequencing.com credentials and authorizes your app to connect to her genetic data. Her app will then remain connected to her genetic data at Sequencing.com unless she revokes access. While the user has the option to revoke access at any time, most users connect an app to their Sequencing.com account once and then leave it connected.

The next day the user feels hungry and is passing by a McDonalds so she walks into the restaurant. Your app detects via GPS that she just walked into a fast food restaurant so the +RTP API is triggered and an API call for Chain73 is sent to Sequencing.com. Sequencing.com returns an almost immediate response that the user's genes indicate she has a 'Very High' risk for a heart attack. Your app sends the user a push notification that she should strongly consider a different restaurant and identifies several nearby restaurants that would be much better for her health.

A different user of your app also walks into McDonalds around that same time. Your app sends a +RTP API call to Sequencing.com for Chain73 and, for this user, the response is 'Slightly Increased risk' of a heart attack. Instead of advising the user go to a different restaurant, your app sends a push notification to the user that identifies healthier options on the McDonalds menu for the app user to consider.

By customizing your app based on the results of the +RTP API, your app is able to provide a truly personalized user experience to each app user. And since the +RTP API returns responses in milliseconds, the personalization can occur in real-time.

Sequencing.com’s GitHub repositories provide free access to the code of a growing number of open source apps that use RTP technology.

Are you down with RTP?

Interested in competing to create innovative apps that use Sequencing.com's Real-Time Personalization (+RTP) API? Want to be at the forefront of a new technological revolution?

Sequencing.com's Hack the Genome^TM hackathons will allow you to show your skills to the world, receive financial backing and IT support to implement future apps and win some amazing prizes.

Hack the Genome 2 is co-hosted by Microsoft, LifeNome and Sequencing.com.

The two-day competition will take place at Microsoft's offices in Times Square, New York City on December 2-3, 2017!

REGISTER TO COMPETE

Past Hackathons

Hack the Genome 1: Sequencing.com's first Hack the Genome hackathon was co-hosted by Sequencing.com and Microsoft at Microsoft's Headquarters in Redmond, Washington on April 6-7, 2017.  Learn more

Interested in developing apps that can access the app user's genes and provide them with truly personalized user experiences?

Sequencing.com's Personalization^®​ technology adds the ultimate Personalization to your software apps... a personalized user experience delivered in real-time that's based on each app user's genes.

We accomplished this by translating the genetic code into software code and making it available to you as simple APIs called App Chains.

Related

Plugins and Code Snippets

This section contains references to codebases published by Sequencing.com as open source on our GitHub repository.

Master Plugins and Code Snippets

• An all-in-one plugin providing full API functionality that works out-of-the-box.
• Includes all core Sequencing.com APIs for rapid application development.

Sample Applications

• Applications you can use as a quick all-in-one bootstrap with master plugin integrated.
• They work out of the box.
• Full-fledged applications that include the Master Plugin

Example of an app with +RTP (Weather My Way +RTP)

• Full-fledged open sourced reference applications developed by Sequencing.com published in Apple App Store and Google Play.

The documentation below provides guidance for integrating Sequencing.com Master plugin into your iOS Swift mobile application.

We developed a pluggable Cocoapods component to simplify adding +RTP into your mobile app.

• iOS Swift Master Plugin
• If you are new to Cocoapods, refer to the official guide.

There are several prerequisites in order to complete the integration:

• register for a Sequencing.com account
• generate an OAuth2 secret

Prepare environment

1) Create Podfile in your project directory

$ pod init

2) Specify "sequencing-master-plugin-api-objc" pod parameters in Podfile

pod 'sequencing-master-plugin-api-swift', '~> 1.3.1'

3) Install the dependency in your project

$ pod install

4) Open the Xcode workspace instead of the project file

$ open *.xcworkspace

5) As a result you'll have 3 CocoaPod plugins installed: OAuth, Files Selector and App Chains

Integrate plugin

1) Integrate OAuth2 integration by following integration instructions from this guide

2) Integrate file selector logic by following integration instructions from this guide

• Note: you do not need to integrate any additional Cocoapods dependencies from OAuth2/File selector/App Chains guides because "sequencing-master-plugin-api-objc" contains already everything needed.

The documentation below provides guidance for integrating Sequencing.com Master plugin into your Android Java application.

We have developed a pluggable Gradle component to simplify adding +RTP into your mobile app.

• Android Java Master Plugin
• If you are new to Gradle, refer to the official guide.

There are several prerequisites in order to complete the integration:

• register for a Sequencing.com account
• generate an OAuth2 secret

Prepare environment

1) Create a new Android Gradle based project (i.e. in Android Studio or Eclipse)

2) Add Gradle dependencies

dependencies { compile 'com.sequencing:master-plugin:1.0.32' }

3) Add Gradle jcenter repository

repositories {
   jcenter()
}

Integrate plugin

1) Integrate OAuth2 integration by following integration instructions from this guide. 

2) Integrate file selector logic by following integration instructions from this guide. 

• Please note that you will not need to integrate additional Gradle dependencies from OAuth2/File selector/App Chains guides because "com.sequencing:master-plugin" already contains everything needed.

Sequencing.com's Sample Applications provide a quick, all-in-one bootstrap that includes the Master Plugin. They work out of the box so you don't even have to follow our integration guides.

The following implementations are available:

Android application in Java

• Clone via git and use in Eclipse or IntelliJ Idea.

iOS application in Objective-C

• Clone via git and use in XCode

iOS application in Swift

• Clone via git and use in XCode

iOS Screenshots
 

Android Screenshots
 

Postman can be used to evaluate the +RTP API. 

Steps performed at Sequencing.com

Step A: Obtain an oAuth2 secret for your app

Step B: Identify an App Chain number to use

Steps performed using Postman

Step 1: Create new request

Step 2: For the 'Authorization type' select OAuth 2.0

Step 3: Click 'Get New Access Token' and setup all parameters according to your app (the parameters below are just examples)

Client ID= [Name of your app]

Scope= External

Step 4: Authenticate and allow request

Step 5: Receive access token for usage

Step 6: Enter URL, change type to POST and add content-type header. The Authorization header will be added by Postman.

Step 7: Go to Body, select 'raw' and enter request

Step 8: Click 'Send' and observe the results

Step 9: Retrieve File List

Questions? Please submit a Support Request.

Registering an app and receiving an oAuth2 secret for an app called Feed.me

1) Log in to Sequencing.com

2) Click Developer Center

3) Click on Generate OAuth2 Secret link

4) Register your app by entering

• App Name (will also be your App ID):  feedme
  Application name should be an alphanumeric identifier.
• App Description:  Provides personalized food recommendations for weight loss and health optimization based on both the user's genes and restaurant menus the user is viewing on the Grubhub, Seamless or Eat24 app.
• Redirect URL: https://feedme.com/token.php

5) Click the 'Generate OAuth2 secret' button

6) The generated OAuth2 Secret will appear, which will be a long string of numbers and characters

Once you have your OAuth secret generated, the following actions may be done:

1. View and modify your secrets
   • go to the Developer Center
   • click 'Generate OAuth2 secret'
2. Monitor API usage for each OAuth2 secret
   • go to the Developer Center
   • click 'Manage OAuth2 secrets'

Here we will show how to quickly integrate Sequencing OAuth2 harnesses into your Android/Java based environment.

We have developed a Maven/Gradle component to simplify using Sequencing OAuth2 library in your project. If you are new to Maven/Gradle, refer to the official guide.

There are several prerequisites in order to complete the integration:

• you need to have a Sequencing account
• you need to have an OAuth2 application secret

In order to complete integration follow instructions below

Prepare environment

1) Create new or open existing Android Gradle based project (i.e. in Android Studio or Eclipse)

2) Add following Gradle dependency

dependencies {
    compile 'com.sequencing:android-oauth:1.0.22'
}

2) Add Gradle jcenter repository

repositories {
   jcenter()
}

Configure authorization

1) Add imports

import com.sequencing.androidoauth.core.OAuth2Parameters;
import com.sequencing.androidoauth.core.ISQAuthCallback;
import com.sequencing.androidoauth.core.SQUIoAuthHandler;
import com.sequencing.oauth.core.Token;

2) Specify your application parameters at AuthenticationParameters. Authorization plugin use custom url schema.

These parameters should conform your application confiiguration

AuthenticationParameters parameters = new AuthenticationParameters.ConfigurationBuilder()
            .withRedirectUri("feedme://login")
            .withClientId("feedme")
            .withClientSecret("RCGK_tcZliZw2z5BqCSr_r-psBTTGBqji_WWEyjNZnp8-eQ1hgle5d1IS_of_U7wkshNvCqXBs25B6Q7JL1EBA")
            .build();

3) Implement ISQAuthCallback, which is needed for your application to get Token passed on successful authentication or to get notified in case authentication failed

/**
 * Callback for handling success authentication
 * @param token token of success authentication
 */
void onAuthentication(Token token);
 
/**
 * Callback of handling failure authentication
 * @param e exception of failure
 */
void onFailedAuthentication(Exception e);

4) Create View that will serve as initial element for authentication flow. It can be a Button or an extension of View class. Do not define onClickListener for this View.

5) Create SQUIoAuthHandler instance that is handling authentication process

6) Register your authentication handler by invoking method authenticate on SQUIoAuthHandler passing view, callback and app configuration

public void authenticate(View viewLogin, final ISQAuthCallback authCallback, AuthenticationParameters parameters);

Here we will show how to quickly integrate Sequencing OAuth2 harnesses into your JEE based environment.

There are several prerequisites in order to complete the integration:

• you need to have a Sequencing account
• you need to have an OAuth2 application secret
• you need to have at one of IDEs - Eclipse, IntelliJ Idea or Netbeans

Sequencing.com provides 2 possibilities to integrate OAuth2 for JEE environments

• Pure servlet based
• Spring boot based

Servlet based environment integration

1) Visit https://github.com/SequencingDOTcom/OAuth2-code-with-demo repository
2) Clone repository locally to your environment

$ git clone https://github.com/SequencingDOTcom/OAuth2-code-with-demo.git

3) Servlet based Maven project is in "java-servlet" folder

4) Review pom.xml and integrate dependencies into your project

5) Review web.xml and integrate servlet definitions into your project

6) Copy classes from com.sequencing.oauth2demo.servlet to your project

7) Edit configuration settings in SequencingServletContextListener class so to make them conform your OAuth2 application settings. Make sure that application name, secret and redirect URL matches. 
OAuth2 management interface is available in the developer center under "Manage OAuth2 secrets" section.

After authorization is completed tokens can be accessed by following call. We recommend keeping them safe.

SequencingOAuth2Client oauthClient = (SequencingOAuth2Client) config.getServletContext().getAttribute(SequencingServletContextListener.CFG_OAUTH_HANDLER);
oauthClient.getToken();

Spring boot based environment integration

1) Visit https://github.com/SequencingDOTcom/OAuth2-code-with-demo repository
2) Clone repository locally to your environment

$ git clone https://github.com/SequencingDOTcom/OAuth2-code-with-demo.git

3) Servlet based Maven project is in "java-spring" folder

4) Review pom.xml and integrate dependencies into your project

6) Copy classes from com.sequencing.oauth2demo to your project

7) Edit configuration settings in application.properties file so to make them conform your OAuth2 application settings. Make sure that application name, secret and redirect URL matches. 
OAuth2 management interface is available in the developer center under "Manage OAuth2 secrets" section.

After authorization is completed tokens can be accessed by following call. We recommend keeping them safe.

// inject dependency first
@Autowired
private SequencingOAuth2Client oauth;

// access token in this way
oauth.getToken();

Testing result

1) Deploy and start application

2) Point your browse to http://feedme.com/Default/AuthCallback
It will trigger redirect to Sequencing authorization page

After entering credentials you will be presented with access approval which contains application details

After clicking on "Yes (I authorize access)" result page will render (result.php) that contains list of sample files available in your account

Here we will show how to quickly integrate Sequencing OAuth2 harnesses into your Perl based environment.
 

There are several prerequisites in order to complete the integration:

• you need to have a Sequencing account
• you need to have an OAuth2 application secret
• you need to have at least a Linux environment with Apache2 with 
• you need a Perl with following packages installed via CPAN
  • JSON
  • HTTP::Request::Common
  • LWP::UserAgent
  • Data::Dumper
  • HTML::Entities
  • CGI::Session

Let's assume you have a website located in /var/www/html folder.

Configure Apache cgi handler for Perl scripts

<Directory /var/www/html/oauth>
      Options Indexes FollowSymLinks ExecCGI
      AllowOverride All
      Order allow,deny
      Allow from all
      AddHandler cgi-script .pl
</Directory>

In order to complete integration follow instructions below

1) Visit https://github.com/SequencingDOTcom/OAuth2-code-with-demo repository

2) Clone repository locally to your environment

git clone https://github.com/SequencingDOTcom/OAuth2-code-with-demo.git

3) Copy Perl resources to your hosted folder

mkdir /var/www/html/oauth
cp OAuth2-code-with-demo/perl/* /var/www/html/oauth/

4) Now, edit configuration settings in /var/www/html/oauth/index.pl so to make them conform your OAuth2 application settings. Make sure that application name, secret and redirect URL matches. 

OAuth2 management interface is available in the developer center under "Manage OAuth2 secrets" section.

For our test feedme application mentioned the section and looking as shown below, 

index.pl should be changed as follows 

5) Point your browse to http://feedme.com/oauth/index.pl

It will trigger redirect to Sequencing authorization page

After entering credentials you will be presented with access approval which contains application details 

After clicking on "Yes (I authorize access)" result page will render (result.php) that contains list of sample files available in your account.

From the code perspective you need to note several important variables that are needed to communicate with Sequencing backend. Those are $access_token  obtained on line 185 of index.pl. We recommend storing them in user session and keeping safe.

Here we will show how to quickly integrate Sequencing OAuth2 harnesses into your Python based environment.
 

There are several prerequisites in order to complete the integration:

• you need to have a Sequencing account
• you need to have an OAuth2 application secret
• you need to have at least environment with Python 2.7

In order to test integration follow instructions below

1) Visit https://github.com/SequencingDOTcom/OAuth2-code-with-demo repository

2) Clone repository locally to your environment

git clone https://github.com/SequencingDOTcom/OAuth2-code-with-demo.git

3) Copy Python resources to your folder

$ mkdir /opt/oauth-site
$ cp OAuth2-code-with-demo/python-django/* /opt/oauth-site

4) Set up virtual environment and setup prerequisites

$ cd /opt/oauth-site
$ apt-get install python-virtualenv
$ virtualenv myvenv
$ source myvenv/bin/activate
$ pip install -r requirements.txt

5) Edit URL mapping in oauth2demo/urls.py, so urlpatterns look as follows

urlpatterns = [
    url(r'^$', views.auth),
    url(r'^sequencing/authorize', views.auth_callback),
    url(r'^sequencing/authorization-approved', views.api, name="api"),
]

6) Now, edit configuration settings in oauth2demo/appconfig.py so to make them conform your OAuth2 application settings. Make sure that application name, secret and redirect URL matches. 
OAuth2 management interface is available in the developer center under "Manage OAuth2 secrets" section.

For our test feedme application mentioned the section and looking as shown below

appconfig.py should be changed as follows 

7) Run server

sudo /myvenv/bin/python manage.py runserver 80

8) Point your browse to http://feedme.com/sequencing/authorize
It will trigger redirect to Sequencing authorization page

After entering credentials you will be presented with access approval which contains application details

After clicking on "Yes (I authorize access)" result page will render list of sample files available in your account.

From the code perspective you need to note several important variables that are needed to communicate with Sequencing backend. Those are access_token and refresh_token that are obtained on lines 75-76 of oauthclient.py

We recommend storing them in user session and keeping safe.

OAuth2 terminology uses the word "secret" - it's no different from a key that identifies your application.

Overview

• OAuth2 secrets are free for development use using the 'Free' subscription plan.
  • When an app and it's OAuth2 secret reaches the maximum # calls it will be temporarily inactivated.
  • To avoid inactivation or to re-activate a secret
    • go to My OAuth2 secrets, find the secret and click 'Edit'
    • choose an app subscription plan
    • under Payment Methods, select a saved card or add a new credit or debit card.
• Monitor usage of your secrets by clicking on Apps and then Usage.
• You can generate and use an unlimited number of OAuth2 secrets.
• Each OAuth2 secret can only be used in a single app.
  • Using the same OAuth2 secret in more than one app is a security risk and a violation of our TOS.
  • Swapping OAuth2 secrets from one app to another is also a security risk and TOS violation.
• OAuth2 secrets are confidential and should not be shared.

Redirect URI

The oAuth2 Redirect URI is used as the way for the OAuth2 provider (Sequencing.com) to send secure responses to the OAuth2 user (your app). The Redirect URI is either a http or https URL.

• If your app is a mobile app (iOS or Android), you may use custom schema, for example: wmw://login
• If your app will be installed directly on a Mac, Windows or Linux, type the word blank into the Redirect URI field
• If your app is a browser (web) based app (ie will be displayed via a browser such as Chrome, Firefox, Safari, Edge, Opera, etc.), a Redirect URI is required. Please see instructions below.

Redirect URI requirements for browser-based apps:

• The Redirect URI is the URL where the response to the authentication will be redirected. This should be the URL within your application that will receive the OAuth2 credentials.
• Wildcard redirect_uri values are also accepted in the request as long as the base url matches the Redirect URI that is registered at the time the OAuth2 secret is generated.
• The Redirect URI can be either HTTP or HTTPS, although we strongly recommend HTTPS.
• Here's an example of a redirect URI: https://mysite.com/token.php

Interested in learning more? Check out this OAuth2 tutorial. Thanks Jakob!

Authentication URL

The Authentication URL is the URL your app should redirect the user to so that the app user can authenticate with Sequencing.com. This is necessary because the user must be registered at Sequencing.com.

Your app users do not need to have genetic data stored at Sequencing.com.  We've made it easy for all users to experience apps powered by Real-Time Personalization technology by providing fun sample data that is free for everyone to use. For example, your users can choose the genes of some interesting people, such as Homer (a white dude from the USA) or Ugg (a caveman that lived 45,000 years ago).*

You may use your own login during the development process to gain access to the sample files and data.

The authentication URL at Sequencing.com is

https://sequencing.com/oauth2/authorize?redirect_uri=[your-redirect-url]&response_type=code&state=[some-random-state]&client_id=[your-id]&scope=[space separated list of scopes]

Please note the following parts in the URL above (do not include the [brackets])

• Base URL: https://sequencing.com/oauth2/authorize
• Method: GET
• Redirect URL: This is your URL = https://mysite.com/token.php
• State: For default, make some-random-state = current
• Client ID: This is the client_id that you created when registering the app
• Scope: For default, make [space separated list of scopes] = all

Authorization Code Token

If the user authentication is successful then the redirect will contain an authorization code.

Please grab the authorization in code and then make a GET request as follows:

1. Base URL
   https://sequencing.com/oauth2/authorize
2. Include the following in the header
   Authorization: Basic base64_encode([your-client-id] . ':' . [your-client-secret])
3. Include the following in the body arguments such in form-url-encoded
   grant_type=authorization_code
   code=[the-code-you-got-from-above]
   redirect_uri=[your-redirect-url]

Access Token

When the call https://sequencing.com/oauth2/authorize is made with the correct information, the oAuth token will be returned. Grab this token in your code as it will be required for all API calls.

• The API token must be sent with each API call made by your app to Sequencing.com.
• The API token serves two purposes:
  • allows for secure API access
  • identifies the user 
    • Allows the app to access and receive user-specific files that are securely stored in the user's Sequencing.com account.

Once your app has the API access token, you can start making API calls using App Chains.

Send the authentication token within the authentication header and Sequencing.com's API will handle the token.

Refresh Access Token

If the OAuth access token has expired, it may be refreshed by making a request to the OAuth server and passing in the expired OAuth token. 

• Base URL: https://sequencing.com/oauth2/authorize
• Method: GET
• Include the following in the header
  Authorization: Basic base64_encode([your-client-id] . ':' . [your-client-secret])
• Include the following in the body arguments such in form-url-encoded
  grant_type=refresh_token
  refresh_token=OAuth Token

 where "OAuth Token" is your refresh token retrieved during authorization

*The genetic data for Ugg is from an actual caveman whose DNA was extracted from a frozen bone discovered by scientists. Scientists, however, haven't yet acquired the actual genetic data for Homer Simpson but we've made a close match. Homer's sample file is the genome of a white dude from Utah who is married with children.

This section contains language specific APIs description for AppChains.

In order to use AppChains API, you need to obtain OAuth token first. For all details please check here.

For following languages we have already code that you can simply integrate and reuse in your projects:

• Swift
• Objective-C
• Java/Android
• PHP
• Perl
• Python
• C#/.NET

If your language is not on the list, let us know and we add implementation for it!

If you are interested in how our HTTP API for AppChain API work, please see details below.

1 Endpoints specification

In order to utilize all power of AppChains API you need to use following endpoints:

1. AppChains submission endpoint
2. AppChains result retrieval endpoint

AppChains support several operation types:

• Single chain request - using this way you can only request single AppChain per specific genetic data file
• Batch chain request - this way allows to request multiple different AppChains for different genetic data files

1.1 Single chain endpoints

1.1.1 Submit single AppChain request

• Endpoint: https://api.sequencing.com/v2/StartApp
• HTTP method: POST
• Request format: JSON
• Response format: JSON

Request headers specification

Request body format specification

Request body example

{
  "AppCode": "Chain88",
  "Pars": [
    {
      "Value": "227679",
      "Name": "dataSourceId"
    }
  ]
}

This request means following:

• It asks to execute Chain with ID 88 against file with ID 227679
• File with ID 227679 corresponds to sample genome available to all users "Homer (Sequencing.com Sample Genome)"
• Chain88 corresponds to Vitamid D level assessment chain. Check here for more details

This endpoint may reply with App Chain result, however in case more time needed for processing, you will have to call "GetAppResults" endpoint for checking results.

Response body format specification

ItemDataValue object structure is shown below

Status object structure is shown below

Response example

{
  "ResultProps": [
    {
      "ChartSeries": [
        
      ],
      "Description": null,
      "Hidden": false,
      "Name": null,
      "SubTitle": null,
      "SubType": null,
      "Title": null,
      "Type": "Pdf",
      "Value": "425644",
      "ViewTablesMd": null
    },
    {
      "ChartSeries": [
        
      ],
      "Description": null,
      "Hidden": true,
      "Name": "result",
      "SubTitle": null,
      "SubType": null,
      "Title": null,
      "Type": "PlainText",
      "Value": "No",
      "ViewTablesMd": null
    },
    {
      "ChartSeries": [
        
      ],
      "Description": null,
      "Hidden": true,
      "Name": "RiskDescription",
      "SubTitle": null,
      "SubType": null,
      "Title": null,
      "Type": "PlainText",
      "Value": "NA",
      "ViewTablesMd": null
    },
    {
      "ChartSeries": [
        
      ],
      "Description": null,
      "Hidden": true,
      "Name": "SourceFileName",
      "SubTitle": null,
      "SubType": null,
      "Title": null,
      "Type": "PlainText",
      "Value": "Homer (Sequencing.com Sample Genome)",
      "ViewTablesMd": null
    }
  ],
  "Status": {
    "CompletedSuccesfully": true,
    "FinishDt": "\/Date(1488305938670+0000)\/",
    "IdJob": 425643,
    "Status": "Completed"
  }
}

Request submission example

curl -X POST -H "Authorization: Bearer your_access_token" -H "Content-Type: application/json" --data '{"AppCode": "Chain88","Pars":[{"Value": "227679","Name": "dataSourceId"}]}' https://api.sequencing.com/v2/StartApp

Where "your_access_token" is a token received as a result of OAuth2 authentication. 

1.1.2 Retrieve aingle AppChain result

• Endpoint: https://api.sequencing.com/v2/GetAppResults
• HTTP method: GET
• Response format: JSON

Request headers specification

Request parameters specification

Response body format specification

Same as in section 1.1.1

Request submission example

curl -X GET  -H "Authorization: Bearer your_access_token" "https://api.sequencing.com/v2/GetAppResults?idJob=425643"

Where "your_access_token" is a token received as a result of OAuth2 authentication. 

1.1.3 Retrieve AppChain report file

• Endpoint: https://api.sequencing.com/v2/GetReportFile
• HTTP method: GET
• Response format: octet/stream

Request headers specification

Request parameters specification

Request submission example

curl -X GET  -H "Authorization: Bearer your_access_token" "https://api.sequencing.com/v2/GetReportFile?idJob=425643"

Where "your_access_token" is a token received as a result of OAuth2 authentication. 

1.2 Batch chain endpoints

1.2.1 Submit batch AppChain request

• Endpoint: https://api.sequencing.com/v2/StartAppBatch
• HTTP method: POST
• Request format: JSON
• Response format: JSON

Request headers specification

Same as in section 1.1.1.

Request body format specification

ChainRequest object structure is shown below

Request body example

{
  "Pars": [
    {
      "AppCode": "Chain88",
      "Pars": [
        {
          "Value": "227679",
          "Name": "dataSourceId"
        }
      ]
    },
    {
      "AppCode": "Chain9",
      "Pars": [
        {
          "Value": "227679",
          "Name": "dataSourceId"
        }
      ]
    }
  ]
}

This request means following:

• It asks to execute:
  • Chain with ID 9 against file with ID 227679
  • Chain with ID 88 against file with ID 227679
• File with ID 227679 corresponds to sample genome available to all users "Homer (Sequencing.com Sample Genome)"
• Chain9 corresponds to Skin cancer risk assessment chain. Check here for more details
• Chain88 corresponds to Vitamid D level assessment chain. Check here for more details

This endpoint may reply with App Chain result, however in case more time needed for processing, you will have to call "GetAppResults" endpoint for checking results.

Response body format specification

BatchChainResult object structure is shown below

Response example

[
  {
    "Key": "Chain88",
    "Value": {
      "ResultProps": [
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": false,
          "Name": null,
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "Pdf",
          "Value": "425643",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "result",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "No",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "RiskDescription",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "NA",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "SourceFileName",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "Homer (Sequencing.com Sample Genome)",
          "ViewTablesMd": null
        }
      ],
      "Status": {
        "CompletedSuccesfully": true,
        "FinishDt": "\/Date(1488305938670+0000)\/",
        "IdJob": 425643,
        "Status": "Completed"
      }
    }
  },
  {
    "Key": "Chain9",
    "Value": {
      "ResultProps": [
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": false,
          "Name": null,
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "Pdf",
          "Value": "425645",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "result",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "NA",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "RiskDescription",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "High",
          "ViewTablesMd": null
        },
        {
          "ChartSeries": [
            
          ],
          "Description": null,
          "Hidden": true,
          "Name": "SourceFileName",
          "SubTitle": null,
          "SubType": null,
          "Title": null,
          "Type": "PlainText",
          "Value": "Homer (Sequencing.com Sample Genome)",
          "ViewTablesMd": null
        }
      ],
      "Status": {
        "CompletedSuccesfully": true,
        "FinishDt": "\/Date(1488318127168+0000)\/",
        "IdJob": 425645,
        "Status": "Completed"
      }
    }
  }
]

Request submission example

curl -X POST -H "Authorization: Bearer your_access_token" -H "Content-Type: application/json" --data '{"Pars":[{"AppCode":"Chain88","Pars":[{"Value":"227679","Name":"dataSourceId"}]},{"AppCode":"Chain9","Pars":[{"Value":"227679","Name":"dataSourceId"}]}]}' https://api.sequencing.com/v2/StartAppBatch

Where "your_access_token" is a token received as a result of OAuth2 authentication. 

1.1.2 Retrieve aingle AppChain result

• Endpoint: https://api.sequencing.com/v2/GetAppResultsBatch
• HTTP method: POST
• Request format: JSON
• Response format: JSON

Request headers specification

Same as in section 1.1.1.

Request body format specification

Request body example

{
  "JobIds": [
    425645,
    425643
  ]
}

Response body format specification

Same as in section 1.2.1

Request submission example

curl -X POST -H "Authorization: Bearer your_access_token" -H "Content-Type: application/json" --data '{"JobIds":[425645, 425643]}' https://api.sequencing.com/v2/GetAppResultsBatch

Where "your_access_token" is a token received as a result of OAuth2 authentication.

Sequencing.com's Real-Time Personalization^® (+RTP) API is available via Nuget to facilitate using Visual Studio to add +RTP into C#/.NET apps.

The NuGet plugin can be obtained from:

• https://www.nuget.org/packages/Sequencing-Master-Plugin/2.0.0.6
• https://github.com/SequencingDOTcom/NuGet-Master-Plugin-.NET-C

Package Installation guide

1. In Solution Explorer:

• Click on project context menu
• Select "Manage NuGet Packages for Solution"

2. In the NuGet Packages window:

• Select 'Browse' tab and enter package name "Sequencing.AppChainsSample"
• Specify project where package will be installed
• Click 'Install' button.

Alternative Package Installation

1. Under 'Tools' tab select Tools→NuGet Package Manager→Package Manager Console

2. Insert "Install-Package Sequencing.AppChainsSample" command and then press 'Enter'

Questions or issues?

Sequencing.com's A-Team (App-Team) is here to help. Please submit a Support Request.

Integration

Sequencing.com has already everything to simplify integration of AppChains API into your Objective-C based project.

There are 2 ways of achiving this:

• Get code from our GitHub repository and paste it into your project
• Integrate using our Cocoapod artifacts

For Cocoapods integration please follow next steps

1) If you are new to CocoaPods, check general "Getting started" guide

2) Create Podfile in your project directory:

$ pod init

3) Specify following parameters in Podfile:

pod 'sequencing-app-chains-api-objc', '~> 1.1.0'

4) Install the dependency in your project:

$ pod install

5) Always open the Xcode workspace instead of the project file.

$ open *.xcworkspace

Objective-C module API

Code snippet

Single App Chain retrieval example

AppChains *appChains = [[AppChains alloc] initWithToken:@"<yourAccessToken>" withHostName:@"api.sequencing.com"];
[appChains getReportWithApplicationMethodName:@"<chain id>"
        withDatasourceId:@"<file id>"
        withSuccessBlock:^(Report *result) {
            for (Result *obj in [result getResults]) {
                ResultValue *frv = [obj getValue];
                if ([frv getType] == kResultTypeText) {
                    NSLog(@"\nvalue %@ = %@\n", [obj getName], [(TextResultValue *)frv getData]);
                }
            }
        }
        withFailureBlock:^(NSError *error) {
            NSLog(@"Error occured: %@", [error description]);
        }];

Batch App Chain retrieval example

AppChains *appChains = [[AppChains alloc] initWithToken:yourAccessToken withHostName:@"api.sequencing.com"];
    
// parameters array for batch request as example
NSArray *appChainsForRequest = @[
        @[@"<chain id>", @"<file id>"], 
        @[@"<chain id>", @"<file id>"]
        ];
    
[appChains getBatchReportWithApplicationMethodName:appChainsForRequest
        withSuccessBlock:^(NSArray *reportResultsArray) {
            
            // @reportResultsArray - result of reports (Report object) for batch request, it's an array of dictionaries
            // each dictionary has following keys: "appChainID": appChainID string, "report": *Report object
            
            for (NSDictionary *appChainReportDict in reportResultsArray) {
                
                Report *result = [appChainReportDict objectForKey:@"report"];
                NSString *appChainID = [appChainReportDict objectForKey:@"appChainID"];
                
                NSLog(@"\n\n appChainID: %@\n", appChainID);
                
                for (Result *obj in [result getResults]) {
                    ResultValue *frv = [obj getValue];
                    if ([frv getType] == kResultTypeText) {
                        NSLog(@"\nvalue %@ = %@\n", [obj getName], [(TextResultValue *)frv getData]);
                    }
                }
            }
        }
        withFailureBlock:^(NSError *error) {
            NSLog(@"batch request error: %@", error);
        }];

Integration

Sequencing.com has already everything to simplify integration of AppChains API into your Perl based project.

In order to integrate it, get code from our GitHub repository and paste it into your project. Code is Perl 5.10 compatible and is OO based.

Perl module API

Code snippet

Adding code to the project:

• Add AppChains.pm into your source folder and import AppChains in your Perl file (use AppChains;).

For complete usage example, refer to our code in GitHub repository.

my $chains = AppChains->new("<your token>", "api.sequencing.com");
my $chainsResult = $chains->getReport("StartApp", "<chain id>", "<file id>");
 
if ($chainsResult->isSucceeded()) {
    print "Request has succeeded\n";
} else {
    print "Request has failed\n";
}
 
foreach (@{$chainsResult->getResults()})
{
    my $type = $_->getValue()->getType();
 
    if ($type == ResultType->TEXT)
    {
        my $v = $_->getValue();
        print sprintf("-> text result type %s = %s\n", $_->getName(), $v->getData());
    }
    elsif ($type == ResultType->FILE)
    {
        my $v = $_->getValue();
        print sprintf(" -> file result type %s = %s\n", $_->getName(), $v->getUrl());
        $v->saveTo("/tmp");
    }
}

Batch App Chain retrieval example

my $chains = AppChains->new("<your token goes here>", "api.sequencing.com");

# batch result retrieval
my %chainsSpec = ("Chain9" => "227680", "Chain88" => "227680");
my $out = $chains->getBatchReport("StartAppBatch", \%chainsSpec);

foreach (keys %$out)
{
    my $cr = $out->{$_};
    print "-> Chain ID: " . $_ . "\n";
    handleAppChainResult($cr);
    print "\n\n";
}

Integration

Sequencing.com has already everything to simplify integration of AppChains API into your Swift based project.

There are 2 ways of achiving this:

• Get code from our GitHub repository and paste it into your project
• Integrate using our Cocoapod artifacts

For Cocoapods integration please follow next steps

1) If you are new to CocoaPods, check general "Getting started" guide

2) Create Podfile in your project directory:

$ pod init

3) Specify following parameters in Podfile:

pod 'sequencing-app-chains-api-swift', '~> 2.1.1'

4) Install the dependency in your project:

$ pod install

5) Always open the Xcode workspace instead of the project file.

$ open *.xcworkspace

6) Create bridging header file. Select File > New > File > Header File > name it as

project-name-Bridging-Header.h

7) Add AppChains class import in the bridging header file

#import <AppChainsLibrary/AppChains.h>

8) Register your bridging header file in the project settings. Select your project > project target > Build Settings > Objective-C Bridging Header specify path for bridging header file

$(PROJECT_DIR)/project-name-Bridging-Header.h

Swift module API

Code snippet

Single App Chain retrieval example

let appChainsManager = AppChains.init(token: accessToken as String, withHostName: "api.sequencing.com")
appChainsManager.getReportWithApplicationMethodName("<chain id>", withDatasourceId: "<file id>", withSuccessBlock: { (result) in
        let resultReport: Report = result as Report!
        
        if resultReport.isSucceeded() {    
            if resultReport.getResults() != nil {
                for item: AnyObject in resultReport.getResults() {
                    
                    let resultObj = item as! Result
                    let resultValue: ResultValue = resultObj.getValue()
                    
                    if resultValue.getType() == ResultType.Text {
                        print(resultObj.getName() + " = " + (resultValue as! TextResultValue).getData())
                    }
                }
            }
        } else {
            print("Error occured while getting genetic information")
        }
        
    }) { (error) in
        print("Error occured while getting genetic information. " + error.localizedDescription)
    }

Batch App Chain retrieval example

let appChainsManager = AppChains.init(token: accessToken as String, withHostName: "api.sequencing.com")
let appChainsForRequest: NSArray = [ [ "<chain id>", "<file id>"], ["<chain id>", "<file id>" ] ]

appChainsManager.getBatchReportWithApplicationMethodName(appChainsForRequest as [AnyObject], withSuccessBlock: { (resultsArray) in
        let reportResultsArray = resultsArray as NSArray
        for appChainReport in reportResultsArray {
            let appChainReportDict = appChainReport as! NSDictionary
            let resultReport: Report = appChainReportDict.objectForKey("report") as! Report;
            let appChainID: NSString = appChainReportDict.objectForKey("appChainID") as! NSString;
            
            print(appChainID)
            
            if resultReport.getResults() != nil {
                for item: AnyObject in resultReport.getResults() {
                    
                    let resultObj = item as! Result
                    let resultValue: ResultValue = resultObj.getValue()
                    
                    if resultValue.getType() == ResultType.Text {
                        print(resultObj.getName() + " = " + (resultValue as! TextResultValue).getData())
                    }
                }
            }  
        }
            
    }) { (error) in
        print("batch request error. " + error.localizedDescription)
        completion(appchainsResults: nil)
    }

This API is represented by single endpoint, please find all details below.

Available implementations

We provide implementations in following laguages/platforms:

• JavaScript (could be integrated into any web application).
• iOS: Objective-C, Swift
• Java: Android

If your language is not on the list, let us know and we add implementation for it!

If you are interested on how File selector API works, please see protocol specification below.

HTTP endpoint specification

URL: https://api.sequencing.com/DataSourceList

HTTP method: GET

Response format: JSON

HTTP headers

Request parameters

Any combination of request parameters parameters is allowed and there should be at least one specified.

Since any combination of request parameters is possible, here are few valid examples:

• My uploaded files & Files shared with me

https://api.sequencing.com/DataSourceList?uploaded=true&shared=true

• My uploaded files & Files saved from my apps:

https://api.sequencing.com/DataSourceList?uploaded=true&fromApps=true

Response specification

Response if a list of objects of following structure

Response example

[
  {
    "DateAdded": null,
    "Ext": "vcf.gz",
    "FileCategory": "Community",
    "FileSubType": "Other",
    "FileType": "Other",
    "FriendlyDesc1": "Homer",
    "FriendlyDesc2": "Pretty fly for a white guy",
    "Id": "227679",
    "Name": "Sample genome",
    "Population": "Caucasian (American)",
    "Sex": "Male",
    "WasUsedPreviously": false
  },
  {
    "DateAdded": null,
    "Ext": "vcf.gz",
    "FileCategory": "Community",
    "FileSubType": "Other",
    "FileType": "Other",
    "FriendlyDesc1": "Marge",
    "FriendlyDesc2": "Wise white woman and mother of three",
    "Id": "227682",
    "Name": "Sample genome",
    "Population": "Caucasian (American)",
    "Sex": "Female",
    "WasUsedPreviously": false
  },
  {
    "DateAdded": null,
    "Ext": "vcf.gz",
    "FileCategory": "Community",
    "FileSubType": "Other",
    "FileType": "Other",
    "FriendlyDesc1": "Bart",
    "FriendlyDesc2": "El Barto is 10 and the son of Homer and Marge",
    "Id": "237697",
    "Name": "Sample genome",
    "Population": "Caucasian (American)",
    "Sex": "Male",
    "WasUsedPreviously": false
  }
]

In case token is not valid following response will be sent in a response

{"Detail":null,"ExceptionType":"System.ServiceModel.FaultException","Message":"Invalid apiKey passed"}

You may try following curl command to test API. Substitute "authorization_token" with the token you received as a result of OAuth2 authentication

curl -H "Authorization: Bearer authorization_token" "https://api.sequencing.com/DataSourceList?all=true"

This integration instructions will allow you to integrate file selector capabilities to any web application. This codebase doesn't depend on backend technology and is pure frontend Javascript implementation.

Dependencies:

• Bootstrap
• JQuery 1.11.3+

Initial view

• user can choose to view
  • list of sample files or
  • list of the user's file's that are stored at the user's Sequencing.com account 

Sample files list

• if user selects 'I want to select a sample file' then the list of sample files will appear
• user can select one file 

File selected

• user selected sample file 'Sheila'
• that genetic data in that file will then be used to provide personalized content to the app
• sample files allow user to experience Real-Time Personalization even if they don't yet have their own genetic data

Integration

In order to integrate file selector into your application, please follow instructions below

1) Include Bootstrap and jquery into your project

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="bootstrap/js/bootstrap.min.js"></script>
<link href="bootstrap/css/bootstrap.min.css" rel="stylesheet" />

2) Include file selector JS and CSS files from this repo

• JS file: sequencing-file-selector.js
• CSS file: style.css

<script type="text/javascript" src="sequencing-file-selector.js"></script>
<link href="style.css" rel="stylesheet" />

3) Create a hidden input in your form:

<input type="hidden" name="some-name" />

4) Initialize the file selector on that form element, using this code:

<script type="text/javascript">
    $(document).ready(function() {
        $('#sequencing-file-selector-example').sequencingFileSelector({
            accessToken: 'insert-your-oauth2-access-token-here'
        });
    });
</script>

Make sure to pass token instead of "insert-your-oauth2-access-token-here" placeholder.

5) Get selected file ID

File selector is a JQuery compatible component so once file is selected, selected file ID could be obtained by doing following Javascript call

$('#sequencing-file-selector-example').val()