GenePlaza Developer API

Introduction

The GenePlaza API helps you to quickly develop Genetic Apps to distribute them in our Genetic App Store or to use them on your own site.

Our API is organized around REST. It uses predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

To be able to authenticate you first need to have credentials. Contact us for this.

The GenePlaza API uses API keys to authenticate requests.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

When an analysis is started a webhook of yours is called with the the authorizationCode. Use this authorizationCode to authenticate and get an accessToken back.

Once you have credentials you also need to register an application. You can have several applications registered per account. Each application need to have a two endpoints:

• one webhook for the computation of the customer's results, which is triggered by the developer api when a customer order it.
• one for sending the results of the user to your UX

Authentication with an authorization_code

This is the way authenticate when you want to get access to a dataset genetic information. The authorization_code is sent by us to your webhook registered in your application.

To authenticate, use this code:

# With shell, you can just pass the correct header with each request
curl -X POST \
  https://developer.geneplaza.com/token \
  -H 'authorization: Basic <64encode_usercredentials>' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
         "type": "token",
         "attributes": {
           "grant_type": "authorization_code",
           "code": <authorization_code>,
           "scope": "analysis"
         }
    }
}'

{
    "data": {
        "type": "token",
        "id": "414364fcf3739e2649e90e5089c46c59434cfc99f",
        "attributes": {
            "accessToken": "414364fcf3739e2649e90e5089c46c59434cfc99f",
            "expiresIn": 3600,
            "tokenType": "Bearer",
            "scope": "analysis"
        }
    }
}

Parameters

Parameter	Default	Description
64encode_usercredentials	false	base64 encode of username:password
authorization_code	false	This you get from us with the webhook.

Authentication with credentials

This way of authentication is used for accessing the application endpoints.

curl -X POST \
  https://developer.geneplaza.com/token \
  -H 'authorization: Basic <64encode_usercredentials>' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
         "type": "token",
         "attributes": {
           "grant_type": "client_credentials",
           "scope": "developer"
         }
    }
}'

Parameters

Parameter	Default	Description
64encode_usercredentials	false	base64 encode of username:password

Access genetic traits

Create a dataset

Create a dataset by uploading your data in .txt or .zip format. We support build_37 data from 23andme, AncestryDNA, and MyHeritage. We also accpet zipped vcf Genvoce low-pass sequencing files. This method will return a unique ID which you can use store and re-use to compute traits on this dataset.

Upload data

curl -F ‘data=@path/to/local/genotype/file.[txt|zip]’ \
  -H 'authorization: Bearer <accessToken>' \
  'https://developer.geneplaza.com/upload'

{
    "data": {
        "type": "dataset",
        "id": <datasetId>,
        "links": {
            "self": "https://developer.geneplaza.com/dataset/<datasetId>"
        },
        "attributes": {
            "datasetId": 18
        }
    }
}

Upload a 23andme, AncestryDNA, MyHeritage, or Gencove file and a dataset will be created with a unique ID.

Traits

List traits

curl -X GET -H 'authorization: Bearer <accessToken>' \
   'https://developer.geneplaza.com/traits'

{
    "data": [
      {
        "type": "trait",
        "id": <traitid>,
        "attributes": {
          "name": "ancestry",
          "variants": ["rs23432",..., "rs23432"]
        }
      },
      {
        "type": "trait",
        "id": <traitid>,
        "attributes": {
          "name": "coffee_metabolism",
          "variants": ["rs72893",..., "rs83738"]
        }
      }
    ]
}

This method returns a list of unique IDs and descriptions for all available traits available from the GenePlaza API. Use the <traitid> and a <datasetid> to request traits for given dataset.

Get trait for dataset

curl -X GET -H 'authorization: Bearer <accessToken>' \
'https://developer.geneplaza.com/dataset/<datasetId>/trait/<traitId>'

{
    "data": {
      "type": "trait-result",
      "id": <trait-result>,
      "attributes": {
          "status": "running",
      }
    }
}

OR when ready

{
    "data": {
      "type": "trait-result",
      "id": <trait-result>,
      "attributes": {
          "status": "ready",
          "type": "binary | quantitative",
          "effectSizeDistributions": {
              "EUR": [[x1,y1], [x2,y2], ...],
              "EAS": [[x1,y1], [x2,y2], ...],
              "AFR": [[x1,y1], [x2,y2], ...],
              "AMR": [[x1,y1], [x2,y2], ...],
              "SAS": [[x1,y1], [x2,y2], ...]
          },
          "zScore": 0.5,
          "effectSize": 23.2343,
          "ethnicity": "EUR",
          "genotypeScores": {
            "rs78503206": {
              "genotype": "CC",
              "effectSize": 0.052336227229741565
            },
            "rs6554267": {
              "genotype": "TT",
              "effectSize": -0.0324724484302187
            },
            "rs7227945": {
              "genotype": "TT",
              "effectSize": -0.035994294104095395
            },
            "rs72921001": {
              "genotype": "AA",
              "effectSize": -0.27263571801638176
            },
            "rs75378433": {
              "genotype": "CC",
              "effectSize": 0.05236703124421473
            },
            "rs13412810": {
              "genotype": "GG",
              "effectSize": 0.07638294299624267
            }
          }
        }
      }
    }
}

This will generate and get the trait results for a given datasetId.

Parameters

Parameter	Required	Description
accessToken	true	Your accessToken
datasetId	true	Id of the dataset you which to have access to the genetic data.
traitId	true	The id of the trait you want results for

Deploy App Store applications

Create an application

curl -X POST \
  https://developer.geneplaza.com/applications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  -d '{
    "data" : {
        "type":"application",
        "attributes":{
            "name" : "myApp",
            "description" : "some app",
            "webhook": "http://localhost:400/test",
            "webhookHeaders": {
                "api-key": "secret"
            }
        }
    }
}
'

{
    "data": {
        "type": "application",
        "id": 61,
        "links": {
            "self": "https://developer.geneplaza.com/applications/61"
        },
        "attributes": {
            "name": "myApp",
            "description": "some app",
            "featuredImage": null,
            "productImages": [],
            "cost": 0,
            "qualityRequirement": 0,
            "webhook": "http://localhost:400/test",
            "webhookHeaders": {
                "api-key": "secret"
            }
        }
    }
}

Parameters

Parameter	Required	Description
access_token	true	Your access_token after login
name	true	name of your app
description	true	Description of your app
webhook	true	endpoint we call when analysis is requested by user
webhookHeaders	false	optional if you want to add some headers to the call we do to your endpoint

Update an application

curl -X PATCH \
  https://developer.geneplaza.com/applications/<applicationId> \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  -d '{
    "data" : {
        "type":"application",
        "attributes":{
            "name" : "myApp",
            "description" : "some app",
            "webhook": "http://localhost:400/test",
            "webhookHeaders": {
                "api-key": "secret"
            }
        }
    }
}
'

{
    "data": {
        "type": "application",
        "id": 61,
        "links": {
            "self": "https://developer.geneplaza.com/applications/61"
        },
        "attributes": {
            "name": "myApp",
            "description": "some app",
            "featuredImage": null,
            "productImages": [],
            "cost": 0,
            "qualityRequirement": 0,
            "webhook": "http://localhost:400/test",
            "webhookHeaders": {
                "api-key": "secret"
            }
        }
    }
}

Parameters

Parameter	Required	Description
access_token	true	Your access_token after login
applicationId	true	The id of your application
name	false	name of your app
description	false	Description of your app
webhook	false	endpoint we call when analysis is requested by user
webhookHeaders	false	optional if you want to add some headers to the call we do to your endpoint

Get an application

curl -X GET \
  https://developer.geneplaza.com/applications/<applicationId> \
  -H 'authorization: Bearer <access_token>'

{
    "data": {
        "type": "application",
        "id": 61,
        "links": {
            "self": "https://developer.geneplaza.com/applications/61"
        },
        "attributes": {
            "name": "myApp",
            "description": "some app",
            "featuredImage": null,
            "productImages": [],
            "cost": 0,
            "qualityRequirement": 0,
            "webhook": "http://localhost:400/test",
            "webhookHeaders": {
                "api-key": "secret"
            }
        }
    }
}

Parameters

Parameter	Required	Description
access_token	true	Your access_token after login
applicationId	true	The id of your application

List all your applications

curl -X GET \
  https://developer.geneplaza.com/applications \
  -H 'authorization: Bearer <access_token>'

{
    "data": [
        {
            "type": "application",
            "id": 52,
            "links": {
                "self": "https://developer.geneplaza.com/applications/52"
            },
            "attributes": {
                "name": "Abacavir-response",
                "description": "''",
                "featuredImage": "''",
                "productImages": [],
                "cost": 0,
                "qualityRequirement": 0,
                "webhook": "http://localhost:6001/analysis?humanTraitIds=24&format=jsonapi",
                "webhookHeaders": []
            }
        },
        {
            "type": "application",
            "id": 59,
            "links": {
                "self": "https://developer.geneplaza.com/applications/59"
            },
            "attributes": {
                "name": "myApp",
                "description": "some app",
                "featuredImage": null,
                "productImages": [],
                "cost": 0,
                "qualityRequirement": 0,
                "webhook": "http://localhost:400/test",
                "webhookHeaders": {
                    "api-key": "secret"
                }
            }
        }
    ]
}

Parameters

Parameter	Required	Description
access_token	true	Your access_token after login

Start of an analysis

We call your webhook with following call:

curl -X POST \
  'https://<your_endpoint>' \
  -H 'content-type: application/json'
  -d '{
    "data": {
      "type": "analysis",
      "attributes": {
        "authorisationCode": <authorisationCode>,
        "analysisId": <analysisId>,
        "datasetId": <datasetId>
      }
    }
  }'

Parameter	Description
authorisationCode	Is the code you need for the authentication
analysisId	The id of the analysis you want to create a report for, or you want to set the state to ready or failed. The state is now running.
datasetId	The dataset which you can query genotypes of

Query genotypes

curl -X GET \
  'https://developer.geneplaza.com/datasets/<datasetId>/SNP?names=rs7221412%20rs17822931%20rs2395029%20rs3745274%20rs4363657%20rs9939609%20rs671%20rs1800012%20rs4988235&quality=0.80' \
  -H 'authorization: Bearer <accessToken>' \
  -H 'content-type: application/json'

{
    "data": [
        {
            "type": "snp",
            "id": {},
            "links": {
                "self": "https://developer.geneplaza.com/datasets/18/SNP"
            },
            "attributes": {
                "name": "rs1800012",
                "chromosome": "17",
                "position": "48277749",
                "genotype": "CC",
                "probability": 1
            }
        },
        {
            "type": "snp",
            "id": {},
            "links": {
                "self": "https://developer.geneplaza.com/datasets/18/SNP"
            },
            "attributes": {
                "name": "rs4988235",
                "chromosome": "2",
                "position": "136608646",
                "genotype": "GA",
                "probability": 1
            }
        }
    ]
}

HTTP Request

GET https://developer.geneplaza.com/datasets/18/SNP?names=rs7221412 rs17822931 &quality=0.80

Query Parameters

Parameter	Default	Description
datasetId	null	The dataset of which you want to query genotypes
quality	0.8	quality or probability of the genotype, number between 0 and 1
names	null	list of space separated SNPs ids

Headers Parameters

Parameter	Description
Authorization	Bearer followed by your accessToken

Save an analysis report

curl -X POST \
  'https://developer.geneplaza.com/analysis/<analysisId>/report-pages' \
  -H "authorization: Bearer <accessToken>" \
  -H "content-type: application/json" \
  -d '{
    "data": {
      "type": "page",
      "attributes": {
        "title": "<title>",
        "content": "<content>"
      }
    }
  }'

Once you have computed results with the genetic data of the user, you can save the results of the analysis.

Parameters

Parameter	Required	Description
analysisId	true	Analysis for which you save a report
title	true	Title of the report
content	true	Content of the report
accessToken	true	Your accessToken for this dataset

Finish the analysis

curl -X PATCH \
  'https://developer.geneplaza.com/analysis/<analysisId>' \
  -H 'authorization: Bearer <accessToken>' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
      "type":"analysis",
      "id": <analysisId>,
      "attributes": {
        "status": <analysisStatus>
      }
    }
  }'

Once the analysis is done you can mark it as finished. When the analysis is finished and in state ready it is accessible by the GenePlaza website for the customer. The customer is notified by email.

Parameters

Parameter	Required	Description
analysisId	true	Analysis for which you want to set the state
status	true	ready or error
accessToken	true	Your accessToken for this dataset

Get an analysis

curl -X GET \
  'https://developer.geneplaza.com/analysis/<analysisId>' \
  -H 'authorization: Bearer <accessToken>'

{
    "data": {
        "type": "analysis",
        "id": <analysisId>,
        "links": {
            "self": "https://developer.geneplaza.com/analysis/<analysisId>"
        },
        "attributes": {
            "applicationId": <int>,
            "datasetId": <int>,
            "status": "ready",
            "notes": ""
        }
    }
}

Parameters

Parameter	Required	Description
analysisId	true	Id of the analysis
accessToken	true	Your accessToken for this dataset

Accessing the report in the UI

Introduction - How it works

The content of the report is sent by javascript from the origin https://www.geneplaza.com with postMessage to the your UI endpoint. Your UI endpoint is opened in a iframe in the GenePlaza website.

<targetWindow>.postMessage(
  JSON.stringify({
    preview: true|false,
    lang: "nl|en|fr",
    reportPage: <reportPage>,
    analysisId: <analysisId>
  }), <yourUIOrigin>);

Parameters

Parameter	Description
analysisId	Id of the analysis
reportPage	The content saved by your application for this analysis

Testing your application

Only a certain role can start analysises. To be able to test your application there is an API endpoint made that allows application developers to start analysises and get authorization_code for certain datasets.

Login to get an accessToken

curl -X POST \
  https://developer.geneplaza.com/token \
  -H 'authorization: Basic <64encode_usercredentials>' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
         "type": "token",
         "attributes": {
           "grant_type": "client_credentials",
           "scope": "developer"
         }
    }
}'

{
    "data": {
        "type": "token",
        "id": <accessToken>,
        "attributes": {
            "accessToken": <accessToken>,
            "expiresIn": 3600,
            "tokenType": "Bearer",
            "scope": "developer"
        }
    }
}

Parameters

Parameter	Default	Description
64encode_usercredentials	false	base64 encode of username:password

Start a test analysis

curl -X POST \
  'https://developer.geneplaza.com/analysistest' \
  -H 'authorization: Bearer <accessToken>' \
  -H 'content-type: application/json' \
  -d ' {
        "data" : {
          "type":"analysis",
          "attributes":{
            "applicationId" : <your_application_id>,
            "datasetId" : 18
          }
       }
  }'

{
    "data": {
        "type": "analysis",
        "id": <analysisId>,
        "links": {
            "self": "https://developer.geneplaza.com/analysis/9056"
        },
        "attributes": {
            "applicationId": <applicationId>,
            "datasetId": 18,
            "status": "running",
            "notes": "",
            "authorizationCode": "someAuthorizationCode"
        }
    }
}

Parameters

Parameter	Required	Description
datasetId	true	Id of the dataset you which to have access to the genetic data. For testing are 18 and 227 available
accessToken	true	Your accessToken, got by logging in.
applicationId	true	The id of your application

//-----------------Documentation for use of API-------------------