Get Started with Digital Health API Documentation

You are an early member of what we hope will be a large developer community. We look forward to working closely with the development community to make Digital Health API the platform of choice to create a new wave of FHIR complaint health apps and experiences. We are in the early stages of Digital Health API hub and we welcome the chance to collaborate to make a great experience for developers and end users of digital health apps.

To get started, we recommend you to follow the below stepwise guidelines.

Step 1: Register yourself with us.

Step 2: Create your App

Step 3: Try Out FHIR APIs

       - B2B Flow

       - B2C Flow

Step 4: Use FHIR APIs and Publish your app

 

Step1: Register yourself with us.

  • On home page click on “Register”.
  • You will be redirected to the “Create new account” tab.
  • Fill in the information for creating a new account with us.
  • You will immediately receive an email that your request is pending for approval.
  • Your request approval may take a couple of hours.
  • You will be notified about the approval in another email with further instructions.
     

Step 2: Create your App

  • Go to “My apps” tab and click on “Add a new app” as in below figure.
     

  • Specify a Name for app.
  • Specify a Callback URL (optional). Callback URL is required only for 3-legged OAuth. It should be the URL of your app to be redirected to along with a code, once user logs in and consent is given. This code can then be used to generate access token.
  • Select FHIR-APIs-Product from the list of products.
  • Click on “Create app”.
     

 

 

  • For the created app, you will see the Consumer Key and Consumer Secret as in figure below.

 

  • Your App’s keys will be generated and you will need these keys in Base64 encoding to get an access token for trying out the FHIR APIs via B2B flow. We will see B2B flow in Step 3 shortly.
  • Use an online base64 encoder tool like https://www.base64encode.org/ to get the encoded value of your app’s keys. You will need to enter the value as below in Encode tab as <Consumer key>:Consumer secret>
    E.g. Here this value is encoded as:  E7QpRZnOkJlYvHG8xuOWSs2gLuynYYEx: jKgifzOkBaibcrrL
  • The encoded result value will be used further to get the Access token in B2B flow.

 

Step 3: Try Out FHIR APIs

  • Use the GUI interface in the interactive FHIR Sandbox to test out the APIs.

          Go to Home page. Click on FHIR APIs & SANDBOX.
          Or
          Click here https://healthapix.apigee.com/fhir-patient-api/apis/get 

          On right hand navigation bar, you will find the listed FHIR APIs to try out.
     

  • For trying out the APIs you will need an access token. You can retrieve the access token depending on the type of your application i.e. Trusted or Untrusted.
    • Business to Business (B2B) or Trusted: When the API consumer/developer is trusted partner of API provider, then you access API via OAUTH Client Credential flow or 2 Legged OAUTH model. No end-user consent is required for data access via API.
       
    • Business to Consumer (B2C) or Untrusted: When the API consumer/developer is an untrusted/long tail developer, an end user consent is required for data access via API. This is done through OAUTH Authorization Code flow or 3 Legged OAUTH model.

 

Let’s first see the B2B flow followed by B2C flow.

   

B2B Flow

As a first step, retrieve an access token by following the below steps.

  • Select Authorization under FHIR APIs and click on Client Credentials Grant Type API.
  • Go to Header Parameters, insert value for ‘Authorization’ header with the encoded value generated in Step 2 with the Basic authentication scheme.
    E.g. Basic RTdRcFJabk9rSmxZdkhHOHh1T1dTczJnTHV5bllZRXg6aktnaWZ6T2tCYWliY3JyTA==

    T
    he above used value is a sample .You are requested to use your base64 encoded value of your app credentials.

     
  • Click on “Send”.
     

           ​​​​

 

  • You will get a response with access token as in below figure.
     

​                 ​

  • Next, invoke an API using the retrieved access token.
     
  • Click on any desired API and further select any read interaction.
    For e.g. Patient API -> Read All Patients.
    Ignore ‘OAuth 2.0 Set’ since this is used to demonstrate the B2C flow.

     
  • To send a request, add the access token value as a Bearer token in Authorization header as follows.
    E.g. Bearer 9qnXLVOAGSW6ETMe1jlkSyToLKJT 
     
  • Click on “Send”.
     

          ​

  • You will get a response with all patient records as below.
     

                    ​

This completes the B2B flow. Let's see now the B2C flow.

 

B2C flow

Here Authorization API is not to be used, instead ‘OAuth 2.0 Set’ gets the access token intrinsically for your app.

  • Click on any desired API and further select a read interaction belonging to it. 
    For e.g. Patient API -> Read Patient. 
  • Click on OAuth 2.0 Set as shown in below figure. 
     

 

Note: Ensure pop-up is enabled/allowed for this website always. Watch out for a warning sign in the address bar of the browser.

A login screen pops up as in following figure. This demonstrates that an end-user, whose resources your app is trying to access, is required to authorize. Hence an end-user for demonstration purpose is required to login and authorize your app.  Let’s call this end-user as a ‘demo end-user’.

Please note the ‘demo end-user’ credentials are different from your Apigee devportal credentials since you have registered as a developer of your app.
 

            

 

Two such 'demo end users' are already created for you to proceed faster.

  • Use one of these and click ‘Sign-In with existing ID’:
  • Alternatively, you can choose to register a new end-user too, by clicking on ‘Register’. Use Patient Id of the new user as 13066.
     

            

  • Once signed-in, a consent screen appears for the user’s consent to share its resources with your app.
  • Click on “Agree” on end-user’s behalf.
     

            

  • Once agreed, an access token is sent to your registered app and you will now have ‘OAuth 2.0 Authenticated’.
    Note: The consent decision is stored for all interactions of the particular FHIR API and hence you will see all of them now have ‘OAuth 2.0 Authenticated’ set.
     
  • Now access the Read Patient API by clicking ‘Send’.

Note: Ignore the error ‘Missing value for template parameter(s):id’

There is no need to specify the Patient ID in the request. Patient ID of the end-user will be implicitly used in the request in the implemented B2C flow.

  • You will get the Read Patient response as follows.
     

                      

This completes the BCB flow.

 

Step 4: Use FHIR APIs and Publish your app

  • Use available APIs in your app.
  • When you are ready to publish your app please let us know. In most of the cases, your app will be published on the app gallery within 5 business days.