GraphQL API Overview

Fire Arrow Server exposes a read-only GraphQL API that lets clients fetch exactly the FHIR data they need in a single request. The GraphQL API is ideal for mobile and web applications where minimizing payload size and round trips is important.

Endpoint

All GraphQL queries are sent as HTTP POST requests:

POST /fhir/$graphql

The request body must be JSON with a query field:

curl -X POST http://localhost:8080/fhir/\$graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"query": "{ PatientList { id name { family given } } }"}'

Read-Only by Design

The GraphQL API supports queries only -- there are no GraphQL mutations. To create, update, or delete FHIR resources, use the FHIR REST API.

This separation keeps the GraphQL schema focused on data retrieval while the REST API handles the full CRUD lifecycle.

Authorization

GraphQL operations use dedicated authorization operations that you configure in your validation rules:

GraphQL Operation	Authorization Operation
Fetch a single resource by ID (e.g., Patient(id: "123"))	graphql-read
Search for resources (e.g., PatientList(name: "Smith"))	graphql-search

Example authorization rules for GraphQL access:

fire-arrow:
  authorization:
    validation-rules:
      - client-role: "Patient"
        resource: "Patient"
        operation: "graphql-read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Observation"
        operation: "graphql-search"
        validator: "PatientCompartment"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "graphql-search"
        validator: "LegitimateInterest"

tip

Every resource type you want accessible via GraphQL needs both graphql-read and graphql-search rules. If you only add graphql-read, clients can fetch individual resources by ID but cannot use list or connection queries.

GraphQL Explorer

The admin web UI includes an interactive GraphQL explorer at:

http://localhost:8080/admin/graphql

The explorer provides:

• Schema documentation -- browse all available types, fields, and search parameters
• Auto-complete -- type-ahead suggestions as you write queries
• Query history -- revisit previous queries from your session

This is the fastest way to discover the schema and prototype queries before integrating them into your application.

Configuration

GraphQL support is enabled by default. You can control it in your application.yaml:

hapi:
  fhir:
    graphql_enabled: true

Set graphql_enabled: false to disable the GraphQL endpoint entirely (the FHIR REST API will still be available).

Next Steps

See Queries and Patterns for a detailed guide to the three query types, search parameters, reference resolution, pagination, and complete examples.