FHIR Basics¶

This chapter is the minimum amount of FHIR you need to follow the rest of the quickstart. For a deeper reference, including full search-prefix tables, complete Bundle-type semantics, and HL7 v2-to-FHIR field-by-field mappings. See Resources -> FHIR.

What FHIR is¶

FHIR is the HL7 standard for representing healthcare data as JSON or XML resources and exchanging those resources over RESTful HTTP. A resource is a strongly-typed object (Patient, Observation, MedicationRequest, Encounter, and so on) defined by the FHIR specification at hl7.org/fhir/R4. Each resource page on hl7.org publishes the resource's element list with cardinalities, the search parameters it supports, and example payloads.

QIE works with FHIR resources the same way it works with any JSON or XML message: parse the payload, walk node paths, build new content from templates, and send it back out. The FHIR-specific work is on the network side (URL structure, search syntax, and Bundles) which is what the rest of this chapter covers.

JSON or XML?¶

FHIR allows both. Servers signal which they return through the HTTP Accept header:

Header	Means
`Accept: application/fhir+json`	Return JSON. The default for almost every modern server, and the form this quickstart uses.
`Accept: application/fhir+xml`	Return XML. Useful when consuming an older endpoint or producing CDA-adjacent documents.

QIE handles both. Pick JSON unless a project has a hard XML requirement. It is more compact, easier to read in the Test tab, and the node-path syntax is the JSON form you already know.

The RESTful URL pattern¶

Almost every interaction with a FHIR server is a URL of this shape:

{base_url}/{resourceType}/{id}/{operation | sub-resource}?{parameters}

For example, the HAPI sandbox exposes:

GET  https://hapi.fhir.org/baseR4/Patient/12345               # read one Patient
GET  https://hapi.fhir.org/baseR4/Patient?name=Smith          # search Patients by name
GET  https://hapi.fhir.org/baseR4/Patient/12345/$everything   # operation - get the patient compartment
POST https://hapi.fhir.org/baseR4/Patient                     # create a new Patient
PUT  https://hapi.fhir.org/baseR4/Patient/12345               # update or create with a known id
DELETE https://hapi.fhir.org/baseR4/Patient/12345             # delete

The base_url portion is what you store as a QIE Web Service Connection's Endpoint URL. Everything to the right of the base URL is supplied by the mapping node or destination sender when it makes the call, typically with QIE node tags substituting message values into the path or query string.

The full URL anatomy with every option (operations, search prefixes, search modifiers) is on the reference page: FHIR RESTful URL anatomy.

Search parameters at a glance¶

A FHIR search adds query parameters to the resource-type URL. The most common shape:

GET https://hapi.fhir.org/baseR4/Patient?family=Doe&birthdate=ge1970-01-01&_count=10

The bits worth knowing before the next chapter:

The default operator is eq. Other prefixes (gt, lt, ge, le, sa, eb, ap) attach to the value: birthdate=ge1970-01-01.
Modifiers attach to the parameter name with a colon: name:exact=Doe, gender:missing=true.
Underscored parameters control the search itself: _count limits page size, _id matches the resource ID, _lastUpdated filters by version timestamp.
Each resource page on hl7.org lists the search parameters that resource supports (for example, the Patient search table).

You use these in Searching a FHIR Server.

Bundles¶

A Bundle is a container resource that holds other resources. The Bundle.type element tells the server how to process the contents:

Type	Use when
`searchset`	A server's response to a `GET` search. Each entry is a resource that matched.
`transaction`	Submitting multiple writes that must succeed or fail as one atomic unit. The server resolves intra-Bundle references and rolls back on any failure.
`batch`	Submitting multiple independent writes. Partial failure is allowed.
`message`	An event-driven push, similar to an HL7 v2 BHS/BTS. A `MessageHeader` entry carries the event name.
`document`	A persisted clinical document (e.g. a discharge summary).
`history`	A resource's version history.

The most important detail for the quickstart: a search response is always a searchset Bundle. When you call GET /Patient?... the server returns a Bundle whose entry array contains zero or more Patient resources. Your QIE mapping code reaches into the Bundle to read each entry. It does not see a flat list of Patients.

Full Bundle semantics (transaction against batch processing, reference vs. fullUrl, an annotated transaction example) are on the Resources -> FHIR page.

How QIE plugs in¶

Putting the concepts above next to the QIE features that implement them:

FHIR concept	QIE feature
`base_url` of a FHIR server	Web Service Connection, Endpoint URL
`Accept: application/fhir+json` and other request headers	Static HTTP Headers on the connection (or per-call headers in the sender)
`GET`/`POST`/`PUT`/`DELETE` against a resource URL	REST Web Service Sender or a `qie.callRESTWebService()` call inside a mapping script
OAuth 2.0 / SMART on FHIR authorization	The Authentication Protocol section of the connection. See the OAuth 2.0 Tutorial
Parsing the JSON response	The JSON Message Model and JSON node paths. See the JSON Tutorial
Building a FHIR resource from another format	`qie.evaluateTemplate()` plus a System Variable template

The next chapter puts the first four rows of that table into a working channel against the HAPI sandbox.