FHIR for developers: resources, search, and the REST model

HL7 FHIR (Fast Healthcare Interoperability Resources) is the modern standard for exchanging healthcare data between systems. If you’re building an application that reads patient records, laboratory results, prescriptions, or clinical encounters from a healthcare system, you’re almost certainly working with FHIR. Understanding how FHIR structures data and how its REST API works is essential before using FHIR Query Validator — because the validator’s job is to catch query strings that don’t conform to this specification.

What FHIR is and why it exists

Healthcare data has historically been locked inside proprietary systems that use incompatible formats. A hospital’s electronic health record system, a laboratory’s reporting platform, and a patient’s wearable device each store data differently and speak different protocols. This fragmentation makes it expensive and error-prone to share data across care settings. FHIR solves this by defining a common data model and a REST API that any system can implement. The specification is published by HL7 International and is now mandated by regulation in many countries, including the United States under the 21st Century Cures Act.

Standardized data model

FHIR defines over 140 resource types — structured objects for patients, observations, medications, and more — with precise field names and value sets.

REST API

Every FHIR server exposes a predictable RESTful API. Resources are created, read, updated, and deleted using standard HTTP methods.

Interoperability

Any system that implements FHIR can exchange data with any other FHIR-compliant system, regardless of the underlying vendor or technology.

The FHIR REST API model

A FHIR server exposes its data through a RESTful API with a consistent URL structure. Every request begins with a base URL, followed by the resource type you want to interact with.

https://fhir.example.com/r4/Patient/12345
└─────────────────────┘ └─────┘ └────┘
      base URL          resource  ID
                          type

The four standard HTTP operations map directly to CRUD:

Operation	HTTP method	Example URL
Read a specific resource	`GET`	`GET /Patient/12345`
Search for resources	`GET`	`GET /Patient?family=Smith`
Create a resource	`POST`	`POST /Patient`
Update a resource	`PUT`	`PUT /Patient/12345`
Delete a resource	`DELETE`	`DELETE /Patient/12345`

FHIR Query Validator focuses on search queries — the GET requests that include query string parameters. These are the most structurally complex FHIR requests and the most common source of silent errors.

FHIR R4 as the target specification

FHIR has gone through several major versions. FHIR Query Validator targets FHIR R4 (Release 4), which is the most widely deployed version and the one required by US regulatory mandates. R4 introduced stable resource definitions, mature search parameter specifications, and a comprehensive conformance framework.

When you see R4 in FHIR documentation, it refers to the fourth major release of the FHIR specification. FHIR R4 resources and search parameters are what FHIR Query Validator validates against.

FHIR search query anatomy

A FHIR search query is a URL with a query string. The structure looks simple but has several layers of rules that define what constitutes a valid query.

Patient?family=Smith&birthdate=ge1980-01-01&_count=10
└─────┘ └──────────────────────────────────┘ └───────┘
resource    search parameters and values      control
 type                                        parameter

Search parameters

Each FHIR resource type defines a fixed set of search parameters. These are named fields that you can filter on. For example, Patient supports parameters like family, given, birthdate, gender, and identifier. Using a parameter that doesn’t exist for a given resource — like lastname for Patient — is an error.

Patient search parameters
Observation search parameters
Encounter search parameters

GET /Patient?family=Smith
GET /Patient?given=John&gender=male
GET /Patient?birthdate=1990-06-15
GET /Patient?identifier=MRN-98765

GET /Observation?code=8867-4
GET /Observation?patient=Patient/123
GET /Observation?category=vital-signs
GET /Observation?date=ge2024-01-01

GET /Encounter?status=finished
GET /Encounter?patient=Patient/123
GET /Encounter?date=ge2024-01-01&date=le2024-12-31
GET /Encounter?type=http://snomed.info/sct|11429006

Modifiers

Modifiers change how a search parameter is interpreted. They are appended to the parameter name with a colon.

GET /Patient?name:exact=Smith
                  └────┘
                 modifier

Common modifiers include:

Modifier	Applies to	Meaning
`:exact`	string	Match exactly, case-sensitive
`:contains`	string	Match if value appears anywhere in the field
`:missing`	any	Match resources where the parameter is absent
`:not`	token	Exclude resources with this token value
`:above`	token	Match codes that subsume the given code
`:below`	token	Match codes that the given code subsumes

Prefixes

Date and number parameters support prefixes that change the comparison operator.

GET /Patient?birthdate=ge1980-01-01
                       └┘
                      prefix (greater than or equal)

Prefix	Meaning
`eq`	Equal (default if omitted)
`ne`	Not equal
`lt`	Less than
`gt`	Greater than
`le`	Less than or equal
`ge`	Greater than or equal
`sa`	Starts after
`eb`	Ends before

Chained parameters

Chained parameters let you filter a resource based on properties of a referenced resource. The chain is expressed with dot notation.

GET /Observation?patient.family=Smith
                         └──────────┘
                  chained parameter on Patient

This query returns observations where the referenced patient has a family name of “Smith”. Chains can extend across multiple hops, though most validators and servers have limits.

GET /DiagnosticReport?result.code=8867-4
GET /MedicationRequest?patient.birthdate=ge1990-01-01

Chained parameters are powerful but can be expensive to execute on the server side. Use them when you need to filter across resource boundaries, and be aware that some FHIR servers may not support all chain combinations.

Control parameters

FHIR defines special parameters that begin with an underscore (_). These control query behavior rather than filtering by resource content.

Parameter	Purpose	Example
`_count`	Limit results per page	`_count=20`
`_sort`	Sort results	`_sort=birthdate` or `_sort=-date`
`_include`	Include referenced resources in the response	`_include=MedicationRequest:patient`
`_revinclude`	Include resources that reference matched resources	`_revinclude=Observation:patient`
`_summary`	Return a subset of resource fields	`_summary=true`
`_elements`	Return only specified fields	`_elements=id,name`

Example queries

The following examples show well-formed FHIR R4 search queries that FHIR Query Validator accepts.

Find patients by name and date of birth

GET /Patient?family=Smith&given=John&birthdate=1985-04-22

Searches for patients with family name “Smith”, given name “John”, and a specific date of birth. All three parameters are valid for the Patient resource type.

Find recent vital signs for a specific patient

GET /Observation?patient=Patient/123&category=vital-signs&date=ge2024-01-01&_sort=-date&_count=10

Returns up to 10 vital-sign observations for patient 123, recorded on or after January 1, 2024, sorted with the most recent first.

Find active medications with patient details included

GET /MedicationRequest?patient=Patient/456&status=active&_include=MedicationRequest:medication

Returns active medication requests for patient 456 and includes the referenced Medication resources in the response bundle.

Find lab results by LOINC code

GET /Observation?code=http://loinc.org|2345-7&date=ge2024-06-01

Searches for observations with a specific LOINC code (glucose, serum or plasma) recorded after June 1, 2024. The pipe (|) separates the code system from the code value.

Find encounters using a chained patient name

GET /Encounter?status=finished&patient.family=Johnson&date=ge2024-01-01

Returns finished encounters where the referenced patient has a family name of “Johnson”, limited to the current year. This uses a chained parameter to filter across the Patient resource boundary.

Next steps

How query validation works

Learn how FHIR Query Validator parses these query structures and what it checks at each stage.

FHIR resource types

Understand how resource types determine which search parameters are valid for a given query.

Get Started

Core Concepts

Usage Guide

Reference

FHIR for developers: resources, search, and the REST model

What FHIR is and why it exists

Standardized data model

REST API

Interoperability

The FHIR REST API model

FHIR R4 as the target specification

FHIR search query anatomy

Search parameters

Modifiers

Prefixes

Chained parameters

Control parameters

Example queries

Next steps

How query validation works

FHIR resource types

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage Guide

Reference

Documentation Index

​What FHIR is and why it exists

Standardized data model

REST API

Interoperability

​The FHIR REST API model

​FHIR R4 as the target specification

​FHIR search query anatomy

​Search parameters

​Modifiers

​Prefixes

​Chained parameters

​Control parameters

​Example queries

​Next steps

How query validation works

FHIR resource types

Build docs developers (and LLMs) love

What FHIR is and why it exists

The FHIR REST API model

FHIR R4 as the target specification

FHIR search query anatomy

Search parameters

Modifiers

Prefixes

Chained parameters

Control parameters

Example queries

Next steps