Tutorial: Access FHIR API with Postman

A client application would access a FHIR API through a REST API. You may also want to interact directly with the FHIR server as you build applications, for example, for debugging purposes. In this tutorial, we will walk through the steps needed to use Postman to access a FHIR server. Postman is a tool often used for debugging when building applications that access APIs.

Prerequisites

FHIR server and authentication details

In order to use Postman, you will need to know the following details:

  • Your FHIR server URL, for example, https://MYFHIRSERVICE.azurewebsites.net or https://MYACCOUNT.azurehealthcareapis.com
  • The identity provider Authority for your FHIR server, for example, https://login.microsoftonline.com/{TENANT-ID}
  • The configured audience. For Azure API for FHIR this is https://azurehealthcareapis.com and for the open source FHIR server for Azure, it would be set in the Azure AD resource application registration.
  • The client_id (or application ID) of the client application you will be using to access the FHIR service.
  • The client_secret (or application secret) of the client application.

Finally, you should check that https://www.getpostman.com/oauth2/callback is a registered reply URL for your client application.

Connect to FHIR server

Using Postman, do a GET request to https://fhir-server-url/metadata:

Postman Metadata Capability Statement

In this example, the FHIR server URL is https://fhirdocsmsft.azurewebsites.net and the capability statement of the server is available at https://fhirdocsmsft.azurewebsites.net/metadata. That endpoint should be accessible without authentication.

If you attempt to access restricted resources, you should then an "Authentication failed" response:

Authentication Failed

Obtaining an access token

To obtain a valid access token, select "Authorization" and pick TYPE "OAuth 2.0":

Set OAuth 2.0

Hit "Get New Access Token" and a dialog appears:

Request New Access Token

You will need to some details:

Field Example Value Comment
Token Name MYTOKEN A name you choose
Grant Type Authorization Code
Callback URL https://www.getpostman.com/oauth2/callback
Auth URL https://login.microsoftonline.com/{TENANT-ID}/oauth2/authorize?resource=<audience> audience is https://azurehealthcareapis.com for Azure API for FHIR and https://MYFHIRSERVICE.azurewebsites.net for OSS FHIR server
Access Token URL https://login.microsoftonline.com/{TENANT ID}/oauth2/token
Client ID XXXXXXXX-XXX-XXXX-XXXX-XXXXXXXXXXXX Application ID
Client Secret XXXXXXXX Secret client key
State 1234
Client Authentication Send client credentials in body

Hit "Request Token" and you will be guided through the Azure Active Directory Authentication flow and a token will be returned to Postman. If you run into problems open the Postman Console (from the "View->Show Postman Console" menu item).

Scroll down on the returned token screen and hit "Use Token":

Use Token

The token should now be populated in the "Access Token" field and you can select tokens from "Available Tokens". If you "Send" again to repeat the Patient resource search, you should get a Status 200 OK:

200 OK

In this case, there are no patients in the database and the search is empty.

If you inspect the access token with a tool like https://jwt.ms, you should see content like:

{
  "aud": "https://azurehealthcareapis.com",
  "iss": "https://sts.windows.net/{TENANT-ID}/",
  "iat": 1545343803,
  "nbf": 1545343803,
  "exp": 1545347703,
  "acr": "1",
  "aio": "AUQAu/8JXXXXXXXXXdQxcxn1eis459j70Kf9DwcUjlKY3I2G/9aOnSbw==",
  "amr": [
    "pwd"
  ],
  "appid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "oid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appidacr": "1",

  ...// Truncated
}

In troubleshooting situations, validating that you have the correct audience (aud claim) is a good place to start. The managed Azure API for FHIR uses identity object IDs to restrict access to the service. Make sure that oid claim of the token contains an object ID from the list of allowed object IDs.

Inserting a patient

Now that you have a valid access token. You can insert a new patient. Switch to method "POST" and add the following JSON document in the body of the request:

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

Hit "Send" and you should see that the patient is successfully created:

Patient Created

If you repeat the patient search, you should now see the patient record:

Patient Created

Next steps

In this tutorial, you've accessed a FHIR API using postman. Read about the supported API features in Microsoft FHIR server for Azure.