Integrate the Cloud Healthcare API with API Gateway for SMART-ON-FHIR

[heynidhi]

Google Cloud API Gateway is a fully managed service that makes it easy to publish, secure, monitor, and manage APIs. Google Cloud Healthcare API is a RESTful API that provides access to healthcare data. By integrating API Gateway with Healthcare API, you can securely expose Healthcare API endpoints to your developers and applications and easily integrate them with SMART-ON-FHIR UI.

Prevalent ways to expose Healthcare API endpoints are:

1. Apigee Integration
2. API Gateway Integration

We already have existing documentation on Apigee integration with Healthcare API so in this blog, we’ll talk about the API Gateway integration.

API Gateway can be more cost effective but it provides fewer customizations compared to Apigee. You can decide which services to choose based on your use case and this blog might come to your rescue.

API Gateway provides a number of security features that can help you protect your Healthcare API endpoints. These features include:

• API Keys: API Keys can be used to authenticate requests to your Healthcare API endpoints.
• OAuth 2.0: OAuth 2.0 is a popular authorization framework that can be used to authenticate requests to your Healthcare API endpoints.
• JWT: JWT is a lightweight token format that can be used to authenticate requests to your Healthcare API endpoints.
• Improved performance: The API Gateway instance can be used to cache requests to the Google Cloud Healthcare API. This can improve the performance of the SMART-ON-FHIR app by reducing the number of requests that need to be made to the Google Cloud Healthcare API.

Prerequisites:

• FHIR Store setup
• Configure development environment
• Service Account with necessary permissions to be used by API Gateway (i.e. The role Healthcare FHIR Resource Reader would be required to read FHIR resources)

The key to successful integration is to create OpenAPI configurations that include proper authentication. In this example, we'll look at authorization via Service Account JWT. You can follow openAPI documentation for other use cases.

Adding sample open api configs which can be used for the integration:

1. Use below Security Definitions to accept the Service Account JWT

   securityDefinitions:
     Bearer:
       type: apiKey
       name: Authorization
       in: header
       description: >-
         Enter the token with the `Bearer: ` prefix, e.g. "Bearer abcde12345".​

2. [Config-1] OpenAPI config to fetch all Patients from FHIR Server using the above token

   paths:
     /getPatients:
       get:
         summary: Get all the patients
         operationId: getPatients
         security:
           - Bearer: []  # <-- use the same name here
         x-google-backend:
           # JWT credentials will be passed on as-is to target API
           disable_auth: true
           address: https://healthcare.googleapis.com/v1/projects/<PROJECT-ID>/locations/<LOCATION>/datasets/<DATASET>/fhirStores/<FHIR-STORE-NAME>/fhir/Patient/
         responses:
          '200':
             description: A successful response
             schema:
               type: string​

3. [Config-2] OpenAPI config to fetch specific Patient details based on resource id

   /Patient/{id}:
       get:
         summary: Get single patient
         operationId: getPatient
         parameters:
           - in: path
             name: id
             type: string
             required: true
             description: ID of the patient to get
         security:
           - Bearer: []  # <-- use the same name here
         x-google-backend:
           # JWT credentials will be passed on as-is to target API
           disable_auth: true
           # Below parameter will append the /Patient/{id} to the base url
           path_translation: APPEND_PATH_TO_ADDRESS
           address: https://healthcare.googleapis.com/v1/projects/<PROJECT-ID>/locations/<LOCATION>/datasets/<DATASET>/fhirStores/<FHIR-STORE-NAME>/fhir/      
         responses:
          '200':
             description: A successful response
             schema:
               type: string​

4. Include additional search parameters based on requirements. Example for identifier below

   parameters:
           - in: query
             # accepts name query param
             name: name
             type: string
             description: Get details of patient based on name search parameter​

You can find the sample config here. Feel free to create your custom configs based on the sample for other FHIR resources.

Go to the API Gateway Console and click on `CREATE GATEWAY`. Add variables of your choice in the field `Display Name` and `API ID`, Use the above config in `Upload an API Spec` while creating the API Gateway as shown below:

Finally, click on CREATE GATEWAY to deploy the API Gateway. It might take 5–10 minutes before you can actually start using the APIs. Fetch the GATEWAY-URL from the API Gateway Console.

Test your API

I used the service account authorization using JSON Web Tokens for this POC. But you can choose what works best for you. 

For testing the above APIs, requests would look like:

# Get all Patients [Config-1]
curl -X GET -H "Authorization: Bearer <SIGNED_JWT>" "<GATEWAY-URL>/getPatients"

# Get patient with resource id=b0457c2b-2b25-427f-b2e9-04e8fba2148e [Config-2]
curl -X GET -H "Authorization: Bearer <SIGNED_JWT>" "<GATEWAY-URL>/Pateint/b0457c2b-2b25-427f-b2e9-04e8fba2148e"

# Request with `name` search parameter
curl -X GET -H "Authorization: Bearer <SIGNED_JWT>" "<GATEWAY-URL>/getPatient?name=Clara"

Hope you all found the above information useful. Thanks for reading!