Building Requests

The FHIR interface is a RESTful API, which means that FHIR resources are treated as REST resources. To access a resource, you issue a HTTP request to the resource-specific URL.

Interactions

The FHIR Interface allows you to manage resources with a variety of basic interactions, including:

• Read
• Search
• Create
• Update
• Delete

Basic interactions are performed by issuing a HTTP request to the appropriate resource URL. Some sample requests are shown below. For complete details, see the HL7 FHIR Specification.

Supported Interactions

Not all resources support all interactions. For example, you may not alter Audit Event resources (as that would defeat the purposes of an audit trail), and Practitioners can be updated but not deleted. Specific endpoints may also limit access to interactions, providing read-only access or restricting search operations.

Access Tokens

Every request must include an access token granting you access to the resource. This token should be included in the request’s HTTP header:

Authorization: Bearer YOUR_ACCESS_TOKEN

To find out how to get an access token, see Authentication.

Data Format

FHIR requests use XML format by default. You can request JSON format instead by adding the “_format” query parameter to the request or adding a HTTP “Accept” header.

Format Query Parameter:

[base]/Patient/1234-5678-90AB?_format=json

Header:

Accept: application/json

Summary Searches

Many FHIR records contain a lot of data, and you can improve the performance of your search interactions by requesting only a summary of the matched records. Just add the “_summary” parameter to your search. For example:

[base]/Patient?family=Demoski&given=Helen&_summary=true

Several summary formats are available. See FHIR specification for details.

Linked Records

Few resources in FHIR exist in isolation. For example, an Observation may be associated with a Provider and a Patient, and a Procedure may be associated with a Patient and a Claim.

There are two ways to find linked records. The first is using the “include” search, which will return the requested record and related records of the specified type. For instance, to search for a patient and all observations associated with them, you could do:

https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir/Patient/1234-4567-9012&_revinclude=Observation%3Asubject

If you only wanted the observations, you could instead do a search specifying the “subject.” For example:

https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir/Observation?subject=Patient%2F1234-4567-9012

Notice that the patient here is referenced by its resource ID: subject=Patient/PATIENTID.

You could similarly search for observations by practitioner (provider) by specifying the “encounter practitioner.” For example:

https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir/Observation?encounter.practitioner=Practitioner%2F222-3333-4444-5555

As with the patient, the practitioner here is referenced by its resource ID: encounter.practitioner=Practitioner/PRACTITIONERID

The request explorer is a good way to try out different searches to be sure you’re using the right request options.

Create and Update Requests

POST and PUT operations are used to create (POST) and update (PUT) the specified resource. Both of these contain the resource records within the HTTP request body. These operations expect full records; partial updates are not supported.

When doing updates, typically you would execute a GET operation to get the record, change the necessary fields, and then PUT the modified record back to the server.

For more information about what FHIR fields are supported and how that data is stored in the HIEBus system, see Mapping.

Extended Operations

In addition to the basic RESTful create/read/update/delete interactions, extended operations provide additional ways to interact with the system.

Operations use GET or POST requests, with the operation name (preceded by a ‘$’) appended to the resource address. Some operations act on a resource, some on a resource instance, and some are not resource-specific at all. Some sample requests are shown below. For complete details, see the HL7 FHIR Specification.

The POST body would contain any necessary input parameters, in XML or JSON format.

See the Interface Specification for details about all operations supported by the FHIR Interface.

Patient Identifiers

When updating or creating patient records (using a PUT or POST operation), the record must contain at least one patient identifier without a system specification. This is the main FHIR-specific patient identifier, and is associated with the default system configured for the FHIR endpoint.

    "identifier": [
        {"value": "P-0001"}
    ],

You may optionally include additional identifiers associated with other systems.

    "identifier": [
        {"value": "P-0001"},
        {
            "system": "http://hl7.org/fhir/sid/us-ssn",
            "value": "123-45-6789"
        },
        {
            "system": "http://fhir.careevolution.com/identifiers/CareEvolution/MemberID",
            "value": "Member1001"
        }
    ],

Transactions

You can use a POST operation to the base FHIR endpoint ([base]) to update multiple records in a single transaction.

For example, to create a weight observation we could post the following request bundle, containing patient information (patient1) and an observation (obs1) referencing that patient:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "patient1",
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {"value": "P-0001"}
        ],
        "name": [
          {
            "use": "official",
            "family": ["Doe"],
            "given": ["John"]
          }
        ],
        "gender": "male",
        "birthDate": "2000-12-25"
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "obs1",
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "3141-9",
              "display": "Weight Measured"
            }
          ]
        },
        "subject": {
          "reference": "patient1"
        },
        "valueQuantity": {
          "value": 185,
          "unit": "lbs",
          "system": "http://unitsofmeasure.org",
          "code": "[lb_av]"
        }
      },
      "request": {
        "method": "POST",
        "url": "Observation"
      }
    }
  ]
}

Paging

Since searches may find a large number of records, the FHIR standard uses paging for all search results. Searches return a FHIR Bundle resource with additional information about the pages in addition to the actual search results. For example:

{
  "resourceType"=>"Bundle",
  "type"=>"searchset",
  "link"=>
    [
     {"relation"=>"self",
      "url"=>
       "https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir-r4/Patient?family=Demoski&_count=2"},
     {"relation"=>"first",
      "url"=>
       "https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir-r4/Patient?_query=8ee80008-0650-46c0-a729-59a9aa01c35a&_count=2&_start=1"},
     {"relation"=>"next",
      "url"=>
       "https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir-r4/Patient?_query=8ee80008-0650-46c0-a729-59a9aa01c35a&_count=2&_start=3"}
      ],
    "entry"=> [ ... patient search results ... ]
}

You can control how many results are given per page with the count search option. For example, this query would return only 2 records per ‘page’:

https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir-r4/Patient?family=Demoski&_count=2

The “first” and “next” URLs allow access the first/next pages of the search results. When requesting a page other than the first one, you will also see a “previous” URL.