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.

  1. Example of relative reference to the Patient with logical resource identifier of "d5da4352b3f978a445475a22".
{
  "reference": "Patient/d5da4352b3f978a445475a22",
  "display" : "Tom Sower"
}
  1. 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"
   }
}
  1. 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"
   }
}
  1. 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. And it means that an idemptrance 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 add ‘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 URL from ‘Location’ header to obtain the status of the request or the operation result, if available.

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.