RESTful API

fhir technical technical fhirinteroperabilityhealthcare
Source: HL7 System: http://hl7.org/fhir/http.html Code: RESTful API Reviewed: 05/01/2026 License: CC-BY-4.0

RESTful API

One-sentence definition: In the context of FHIR, a RESTful API is the standard HTTP interaction layer that defines how clients read, create, update, search, and delete FHIR resources on a server — the mechanism through which FHIR data is exchanged in practice.

Full Definition

FHIR is built on REST conventions: resources are identified by URLs, interactions use standard HTTP methods (GET, POST, PUT, PATCH, DELETE), and responses carry standard HTTP status codes. A FHIR server exposes a base URL — the FHIR base URL — and from it, every resource type is reachable at a predictable endpoint pattern ([base]/[ResourceType]/[id]).

The FHIR specification defines a precise set of interactions that conformant servers must support: read (GET a specific resource by id), search (GET a filtered list), create (POST a new resource), update (PUT a full replacement), patch (PATCH a partial update), delete (DELETE a resource), and history (GET past versions). Servers are not required to support all interactions — they advertise which they do in their CapabilityStatement.

FHIR’s RESTful model is the dominant exchange pattern, but not the only one. Bundles can also be used for batch and transaction operations in a single HTTP call, and messaging patterns exist for systems that don’t fit a REST model. The RESTful API is the baseline assumption for most integrations.

For FHIR search parameters, conditional operations, versioning, HTTP headers, and server implementation requirements — see the canonical reference → FHIR Profiling.

Context and Usage

Where This Term Appears

  • Integration documentation — “the FHIR RESTful API” refers to the HTTP endpoints a server exposes
  • Capability statements — servers declare which REST interactions they support per resource type
  • ONC certification criteria — the standardized patient access API requirement specifies a FHIR RESTful API
  • Error messages — HTTP 404, 410, 422 responses are all part of the FHIR RESTful interaction model

Common Usage Examples

In conversation: “The payer’s FHIR RESTful API is live — we can do a GET /Patient?identifier=... to pull the member record.”

In documentation: “Clients must authenticate via SMART on FHIR before calling any endpoint on the RESTful API.”

Relationship to Other Terms

  • FHIR — the standard that defines the RESTful interaction model and resource types
  • Resource — the units of data read, created, and updated through FHIR REST endpoints

Common Misconceptions

Misconception: All FHIR Exchange Is RESTful

  • Incorrect belief: FHIR always means REST — if data is exchanged using FHIR resources, it must be via a RESTful API.
  • Reality: FHIR resources can also be exchanged via messaging (Bundles of type message), documents (Bundles of type document), and bulk data exports (FHIR Bulk Data, which uses an async file-download pattern rather than per-resource REST calls). RESTful is the default and most common pattern, but FHIR separates the resource model from the exchange paradigm.
  • Why it matters: Integrations with bulk data feeds, document exchange systems, or messaging-based workflows use FHIR resources without using the RESTful interaction model. Assuming REST conflates the data format with the transport pattern.

Why This Term Matters

When practitioners say “FHIR API” they almost always mean the RESTful API. It is the exchange pattern behind patient access APIs, provider directory queries, payer-to-payer exchange, and most EHR integrations. Understanding the URL structure, HTTP method semantics, and CapabilityStatement as the discovery mechanism is the entry point for working with any FHIR server.

Cross-References

  • FHIR — the standard that defines the RESTful interaction model
  • Resource — FHIR’s data units, exposed and exchanged through REST endpoints

Last reviewed: January 5, 2026 Definition authority: HL7 International Content status: Canonical reference