FHIR RESTful API Guide

Protocol

Health Gorilla uses FHIR® to provide a lightweight REST-based access layer for standard HL7-defined data models.

The most actual list of endpoints and operations can be found at the following URL:

https://api.healthgorilla.com/fhir/metadata

Security

Health Gorilla implements SMART authorization protocol to grant access to secured FHIR endpoints, that uses OAuth 2.0 authorization flows.
The SMART App Launch configuration is available at the following URL:

https://api.healthgorilla.com/.well-known/smart-configuration

There you can find the list of OAuth authorization endpoints and SMART on FHIR server capabilities.

Transport Layer Security

All HealthGorilla endpoints are accessible only over SSL/TLS1.2+, any plain HTTP calls are rejected.

Versioning

When backwards-incompatible changes are needed then new version of API is added. However your API calls continue to use the version pinned to your account, unless you explicitly request the certain version of API when issuing an access token or ask Health Gorilla support to upgrade your account. It is highly recommended to keep your client code up to date and use the most recent API provided by Health Gorilla.

References

Health Gorilla supports relative literal references and logical references to the resources hosted on a FHIR RESTful server.

Example of relative reference to the Patient with logical resource identifier of "d5da4352b3f978a445475a22".

{
  "reference": "Patient/d5da4352b3f978a445475a22",
  "display" : "Tom Sower"
}

Example of logical reference to the Patient with Health Gorilla internal MRN (patient's global identifier) or external MRN (id2 field) of d5da4352b3f978a445475a22:

{
   "identifier": {
     "type":{ 
            "coding":[ 
               { 
                   "system":"http://terminology.hl7.org/CodeSystem/v2-0203",
                   "code":"MR"
               }
            ]
      },
      "system" : "https://www.healthgorilla.com",
      "value" : "d5da4352b3f978a445475a22"
   }
}

Example of logical reference to the Patient with SSN 001-01-0001:

{
   "identifier": {
     "type": { 
            "coding":[ 
               { 
                   "system":"http://terminology.hl7.org/CodeSystem/v2-0203",
                   "code":"SB"
               }
            ]
      },
     "system" : "http://hl7.org/fhir/sid/us-ssn",
     "value" : "001-01-0001"
   }
}

Example of logical reference to the Practitioner with NPI 1234567893

{ 
  "identifier": {
      "system":"http://hl7.org/fhir/sid/us-npi",
      "value":"1234567893"
  } 
}

Binary resources

If the response contains Attachment resource, then Attachment includes the location (Attachment.url) where the document can be found. You should send HTTP GET request to the specified URL to read the given document.

GET /fhir/Binary/4c4c925d60847d72f652c7f7 HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
X-Request-Id: 15e72676-48c3-11ea-b77f-2e728ce88125

Idempotent Requests

Health Gorilla provides a mechanism to prevent multiple identical requests to be performed several times. The duplicate requests may occur when the initial request fails due to a timeout or network issues, and the client retries it again (Retry Pattern).

To prevent such a problem you need to add to your request a HG-Idempotency-Key header that contains a unique UUID V4 identifier associated with the certain payload.

POST /fhir/RequestGroup HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125
X-Request-Id: 09189c18-48c8-11ea-b77f-2e728ce88125
Content-Type: application/json 
[...omitted for brevity...]

Identical requests with the same idempotency key will produce the same results, but only one of them is actually executed.

Operation results are stored on the server within one hour. After that you can reuse an idempotency key in another request.

If the first idempotent request is not completed yet, then the second request will receive HTTP 202 Accepted response.

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
X-Request-Id: 15e2305e94845d4d2f3f7796
X-Correlation-Id: 09189c18-48c8-11ea-b77f-2e728ce88125
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

If the second idempotent request is different from the first one, then the server returns HTTP 409 Conflict. This means that an idempotance key uniqueness rule is violated.

HTTP/1.1 409 Conflict
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
X-Request-Id: 15e2305e94845d4d2f3f7796
X-Correlation-Id: 09189c18-48c8-11ea-b77f-2e728ce88125
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

We recommend to adding HG-Idempotency-Key header to all your FHIR CREATE operations.

Async Requests

There are some long running operations that may take a significant time to complete. Health Gorilla provides a mechanism to execute such requests in asynchronous mode to prevent network timeout issues.

To execute your request asynchronously you should pass the following header:
Prefer: respond-async
It indicates that the server should run the given request in asynchronous mode. Server immediately returns HTTP 202 Accepted response, and provides the Location header.

GET /fhir/Patient/65e4a45c3c266fc4e5d45c72/$cq-search HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
Prefer: respond-async

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: /fhir/RequestResult/3ce13b5ecb4d6633826caca0
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

Then you should pull the requestResultURL from Location header to obtain the status of the request or the operation result, if available. This requestResultURL will be used to identify the completed async process in the webhook notification method or used for polling the API for the async process status.

Webhook Notification

For retrieving notification of the completion of an async process, Health Gorilla utilizes webhook notifications. These notifications use the FHIR Subscription model.

Creating an Async Notification Subscription

A FHIR subscription must be created for receiving notifications for Asynchronous process completion. A POST must be made to the fhir/R4/Subscription endpoint. The client's access token must be included in the request Headers. An example payload is below. The channel object contains the information for your webhook. The ‘endpoint’ attribute is the endpoint to which Health Gorilla will send the notifications.
More information on creating and managing FHIR subscriptions can be found in the developer guide here: https://developer.healthgorilla.com/docs/subscriptions-1#4-create

  {  
    "resourceType": "Subscription",  
    "status": "active",  
    "end": "2024-12-31T00:00:00Z",  
    "reason": "Monitor async requests and responses",  
    "criteria": "OperationOutcome?async=true",  
    "channel": {  
        "type": "rest-hook",  
        "endpoint": "<https://your Webhook URL">,  
        "payload": "application/fhir+json",  
        "header": [  
            "<Optional Header Field(s)>: <Optional Header Value>"  
        ]  
    }  
}

Receiving the Notification

When the asynchronous process completes, a notification will be sent to the webhook provided in the Subscription. The id of the RequestResult can be found in the issue.id attribute and the complete requestResult URL can be found in the issue.expression attribute. This notification signifies that the asynchronous process has been completed.

 {  
    "resourceType": "OperationOutcome",  
    "issue": \[  
        {  
            "id": "p360_d6fd136614df48c6bb11305d",  
            "severity": "information",  
            "details": {  
                "coding": [  
                    {  
                        "system": "http://hl7.org/fhir/operation-outcome",  
                        "code": "MSG_CREATED",  
                        "display": "New resource created"  
                    }  
                ],  
                "text": "New resource created"  
            },  
            "expression": [  
                "/fhir/R4/RequestResult/p360_d6fd136614df48c6bb11305d"  
            ]  
        }  
    ]  
}

Polling

Clients should check the RequestResult URL if a webhook notification has not been received after 5 minutes. This is a fail safe in case there is a failure during the webhook notification delivery.

Clients should follow an exponential backoff approach when polling for operation results.

GET /fhir/RequestResult/3ce13b5ecb4d6633826caca0 HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
X-Progress: in progress
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

HTTP/1.1 454 Expired or Not Found
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

If the request is not completed yet, then the server returns HTTP 202 Accepted.
If the request can’t be found or expired, then the server returns HTTP 454 Expired or Not Found
Otherwise you receive the result of the initial request. The operation result of the asynchronous request is fully identical to the synchronous version including error response.

Operation results are stored on the server within one hour only.

Request ID

Health Gorilla assigns a unique identifier to each incoming API call and returns it in a X-Hg-Request-Id header.

If unique request identifier is assigned by the client and supplied in X-Request-Id header, then the server returns it in X-Correlation-Id header in the response and also puts the server assigned identifier to X-Request-Id header.

It is highly recommended to include the server assigned request identifier into your error report.

If you have problems with Health Gorilla API then you should provide the request identifier, this may be a client assigned request id or a server assigned request id.

Meta and Security Label

The "meta" element in a FHIR resource is the metadata about the resource. This element is a powerful tool that allows you to tag your data in the system. Tagging the data opens up possibilities to create custom triggers, control data access, and build other tag-based logic that supports your organization needs.

The security labels function similar to a meta tag, except that they follow a FHIR valueset.

FHIR resource:

Meta: https://www.hl7.org/fhir/resource.html#Meta
Security label value set: https://www.hl7.org/fhir/valueset-security-labels.html

Resources that support meta tags are:

1. Create or update the tag or security label in the meta information:

Example:

{
  "resourceType": "Condition",
  "id": "example",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Severe burn of left ear (Date: 24-May 2012)</div>"
  },
   "meta": {
        "versionId": "1653986662411",
        "lastUpdated": "2022-06-31T16:44:22.412+08:00",
        "security": [
            {
                "system": "sl_system3",
                "code": "sl_code3",
                "display": "sl_display3"
            }
            
        ],
        "tag": [
            {
                "system": "t_system3",
                "code": "t_code3",
                "display": "t_display3"
            }
        ]
    },
  
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/condition-category",
          "code": "encounter-diagnosis",
          "display": "Encounter Diagnosis"
        },
        {
          "system": "http://snomed.info/sct",
          "code": "439401001",
          "display": "Diagnosis"
        }
      ]
    }
  ],
  "severity": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "24484000",
        "display": "Severe"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "39065001",
        "display": "Burn of ear"
      }
    ],
    "text": "Burnt Ear"
  },
  "bodySite": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "49521004",
          "display": "Left external ear structure"
        }
      ],
      "text": "Left Ear"
    }
  ],
  "subject": {
    "reference": "Patient/36b92762a00903192a109761"
  },
  "onsetDateTime": "2012-05-24"
}'

2. Search requests using tags and/or security labels

https://api.healthgorilla.com/fhir/R4/AllergyIntolerance?patient=6c7d79719e23e1a54f0f7810&_tag=c_system1|c_code1&_security=sl_system2|sl_code2

You can create expression from AND and OR operators on tags.

For example, this statement:

_tag=c_system1|c_code1,c_system2|c_code2&_tag=c_system3|c_code3

Translates into the following expression:

( 
 (meta.tag.system=c_code1 AND meta.tag.code=c_code1) 
  OR 
  (meta.tag.system=c_code2 AND meta.tag.code=c_code2) 
 ) 

AND 

(meta.tag.system=c_code3 AND meta.tag.code=c_code3)