FHIR GraphQL
FHIR GraphQL API for Digital Health Frontends
Fire Arrow Server exposes a read-only GraphQL endpoint at `POST /fhir/$graphql`. Authorization runs through `graphql-read` and `graphql-search` operations, with the same validators, identity filters, and property filters as REST.
Who this is for
Frontend, mobile, and API teams building FHIR-native applications.
Clinical applicability
A patient dashboard can load demographics, recent vitals, due tasks, and care team in one query, with the underlying searches narrowed to the patient's compartment by the server.
What the endpoint exposes
All queries POST to `/fhir/$graphql`. The Server admin UI ships a GraphQL explorer at `/admin/graphql` with schema documentation, auto-complete, and query history. Server's GraphQL is read-only; create, update, and delete go through FHIR REST. Core's GraphQL supports both read and write since it delegates persistence to the upstream FHIR service.
Three query shapes are supported: single-resource by ID (e.g. `Patient(id: "123")`), list/search (e.g. `PatientList(name: "Smith")`), and reference resolution that pulls related resources inline. Server supports nested queries; Core does not.
Authorization at the GraphQL layer
GraphQL uses dedicated operations: `graphql-read` for fetching a single resource by ID, `graphql-search` for list and connection queries. They are configured through the same rule shape as REST operations, with the same validators (`PatientCompartment`, `LegitimateInterest`, `CareTeam`, and the rest).
Search narrowing applies through alternative search parameter maps. The client does not pass a compartment filter; the server adds one. Property filters and identity filters apply identically.
Inline reference expansion in GraphQL read is the recommended pattern when the role has property filters but should not have full search access. References are resolved by ID, so there is no client-controlled search parameter to use as a side channel.
Configuration
GraphQL is enabled by default. Disable it with `hapi.fhir.graphql_enabled: false` in `application.yaml`. Per-resource exposure is controlled by the rules: a resource type without `graphql-read` or `graphql-search` rules is not reachable through GraphQL even if it is reachable through REST.
FAQ
Why is Server's GraphQL read-only?
The separation keeps the GraphQL schema focused on data retrieval and the REST API as the single write path. Writes still flow through FHIR REST and pass through the same authorization layer. Core supports GraphQL writes because it delegates to an upstream FHIR server.
Do I need both `graphql-read` and `graphql-search` rules?
Yes, if you want both single-resource fetches and list/connection queries. A `graphql-read`-only rule lets a client fetch by ID but not search. This pattern fits property-filtered roles.
How does GraphQL pagination work?
Through the same patterns as FHIR REST search bundles, exposed as connection fields in the GraphQL schema. The Queries and Patterns docs page covers this in detail.
