Guidance

The official example guidence of fhir server.

Overview

The server will be running at localhost at port 2048.

The reload option clears the database and loads sample data. So do not use reload if you have something that you want to keep in the database.

The latest source code for this server can be found at:
https://github.com/chaiery/FHIR-Genomics-2

All code files mentioned below can also be found in this address.

Create a new database

First, clear the database:

$ python server.py clear

Then, you can write scripts to upload your own data. We provide a sample script load_example.py to create and add sequence instances from vcf files and other instances from random data and local json files:

  • observationforgenetics (Genetics profile for Observation),
  • reportforgenetics (Genetics profile for DiagnosticReport),
  • orderforgenetics (Genetics profile for DiagnosticOrder).

Submit data to an existing database

There are many ways to add new data.

  1. Go to http://localhost:2048/ in your browser and login. Then click ‘Submit’ button on the menu bar. To submit data, you need to provide the resource/profile type of the instances you want to add and upload a json file or fill in the text box.
  2. We provide a sample script submit.py. It can help add new data under the user: name@mail.com
  3. We provide API for apps to submit add:
    POST [base]/[type]
    Here is a sample function used in an app to submit sequence instances:
    def api_call(api_endpoint):
        access_token = request.cookies['access_token']
        auth_header = {'Authorization': 'Bearer %s'% access_token}
        return requests.get('%s%s'% (API_BASE, api_endpoint), headers=auth_header)

Entire code for this app can be found at:
https://github.com/chaiery/ga2fhir
web.py

API Reference

The SMART Genomics API is built on top of SMART on FHIR please see here for more information.

Note: The SMART Genomics API supports both XML and JSON formats. Append ?_format = xml|json in HTTP requests to differentiate between the two.

The following operations are defined:

  • read: Read the current state of the resource
  • update: Update an existing resource by its id (or create it if it is new)
  • delete: Delete a resource
  • history: Retrieve the update history for a particular resource
  • create: Create a new resource with a server assigned id
  • search: Search the resource type based on some filter criteria

The Service Root URL is the address where all of the resources defined by this interface are found. The Service Root URL takes the form of:
http://server/api/resourceType


Style:

Read

GET [base]/[type]/[id]

For example:

http://localhost:2048/api/Sequence/[id]

Search

GET [base]/[type]{?[parameters]}

For example:

[http://localhost:2048/api/Sequence?variationID=[variationID]]

Sample codes:

Python:
At first, you may use 'requests' or other python library to post/get/put.

API_BASE = 'http://localhost:2048/api'
#to read data
def read(request, url, id):
    access_token = request.COOKIES['genomic_access_token']
    resp = requests.get('%s/%s/%s?_format=json'%(API_BASE, url, id),
        headers={'Accept': 'application/json','Authorization': 'Bearer %s'% access_token})
    return resp.json()

#to create data
def create(request, url, data):
    access_token = request.COOKIES['genomic_access_token']
    resp = requests.post('%s/orderforgenetics?_format=json'% API_BASE,
        data=json.dumps(data),headers={'Authorization': 'Bearer %s'% access_token})
    return resp.json()

#to update data
def read(request, url, id, data):
    access_token = request.COOKIES['genomic_access_token']
    resp = requests.put('%s/%s/%s?_format=json'%(API_BASE, url, id),
        data=json.dumps(data), headers={'Accept': 'application/json','Authorization': 'Bearer %s'% access_token})
    return resp.json()

#to search data
def search(url, args={}):
    access_token = request.COOKIES['genomic_access_token']
    args['_format'] = 'json'
    resp = requests.get('%s%s?%s'% (API_BASE, url, urlencode(args)),
        headers={'Accept': 'application/json','Authorization': 'Bearer %s'% access_token})
    return resp.json()

JavaScript:
At first, you may need found a js library like 'requestift' or 'jquery' to post/get data.

api.js
var requestify = require('requestify');// a js library
var api_url = 'http://localhost:2048/api'

var doGet = function(url, access_token, res){
  requestify.get(url, {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ' + access_token}
  }).then(function(response){
    res.send(response.getBody());
  });
}

var doPost = function(url, data, access_token, res){
  requestify.post(url, data, {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ' + access_token}
  }).then(function(response){
    res.send(response.getBody());
  });
}

var doPut = function(url, data, access_token, res){
  requestify.put(url, data, {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ' + access_token}
  }).then(function(response){
    res.send(response.getBody());
  });
}

/*
To update data
*/
var update = function(data_type, id, data, access_token, res){
  var url = api_url + '/' +data_type + '/' + id + '?_format=json';
  doPut(url, data, access_token, res);
}

/*
To search data
*/
var search = function(data_type, access_token, res){
  var url = api_url + '/' + data_type + '?_format=json';
  doGet(url, access_token, res);
}

/*
To read data
*/
var read = function(type, id, access_token, res){
  var url = api_url + '/' + type + '/' + id + '?_format=json';
  doGet(url, access_token, res);
}

```
you can get data by using ```res.send(response.getBody())```.
if you use angular.js, you can write code like this.

```

$http.get('/Patient?id=123456').success( function(data) {
    //the data is information about Patient/123456
});

router.get('/Patient', function(req, res, next){
  api.read('Patient', req.query.id, req.session.access_token, res);
})

Scope

FHIR Genomics server supports all resources in FHIR and genetics profiles, which can be retrieved by:

GET /observationforgenetics

GET /reportforgenetics

GET /orderforgenetics

GET /hlaresult

GET /consensus-sequence-block

GET /familymemberhistory-genetic

Authentication

Registration

  • Go to http://localhost:2048 in your browser, register an account and login. Then you can register an application.

    For example:

    #Application Registration
    Application name: Genomics-Advisor
    Redirect URL: http://localhost:8000/recv_redirect
    Launch URL: http://localhost:8000/fhir-app/launch.html
  • Then you will have an App id and an App secret (They correspond to clientid and clientsecret in OAuth2) on your app dashboard.

How to get access to the API using OAuth2

  • redirect your user to the authorization page with following parameters.

    For example, you may be asked for permission to read all of the user's Patient and Sequence resources.

    Configuration:

    client_id: [your client id]
    response_type: "code"
    scope: "user/Sequence.read user/Patient.read"
    // space-delimited list of scope
    redirect_uri: [redirect uri you put on your app dashboard]
    state: [optional, i.e. you whatever you want here]client_id: [your client id]

    In the case of using the local API server, the url of the authorization page is http://localhost:2048/auth/authorize.

  • If everything goes well, the user will be redirected to your redirect uri with following parameters:
    code: [authorization code you will be using to exchange for access token]
    state: [this will be the `state` you put in last step]
  • Now you can exchange your code with a access token, which you can use to access the API.
  • Simply make a POST request to the server, with following data,
    grant_type: "authorization_code",
    client_id: [client id],
    client_secret: [client secret],
    redirect_uri: [redirect uri],
    code: [code you obatined in last step]

    In the case of using the local API server, the url is http://localhost:2048/auth/token

  • You will then get this JSON as a response:
    {
    'access_token': [access token],
    'expires_in': 3600,
    'token_type': 'bearer'
    }
  • Now that you have access token, you can make an authorized request to the API by using this header in your HTTP request.