Skip to main content

FHIR GraphQL API Implementation Guide

Architectural Alignment​

Our implementation maintains strict compliance with HL7 FHIR's GraphQL specification while introducing targeted enhancements for developer experience and performance optimization.

Core Query Patterns​

Entity Access Methods​

# Single resource fetch
query {
  Patient(_id: "a151212e-0ed1-4a19-8ebf-87efbc2c87c2") {
    name { given family }
  }
}

# Basic collection retrieval
query {
  PatientList(name: "Smith") {
    id
    birthDate
  }
}

# Paginated results
query {
  PatientConnection(_count: 50, active: true) {
    edges {
      resource {
        ... on Patient {
          identifier { system value }
        }
      }
    } 
  }
}

Implementation Notes:

  • PatientList: Optimized for small datasets (<1000 records) with direct filtering
  • PatientConnection: Implements cursor-based pagination for large datasets
  • Search parameters mirror FHIR's standard search criteria for each resource type

Mutation Framework​

Standard Operations​

mutation {
  PatientCreate(resource: { name: [{ given: "Joe", family: "Smith" }] }) {
    id
    meta { lastUpdated }
  }
}

mutation {
  PatientUpdate(_id: "123", resource: { active: false }) {
    success
    resource { active }
  }
}

mutation {
  PatientDelete(_id: "456") {
    reference
    deletedAt
  }
}

Key Design Decisions:

  • Delete operations return resource references for audit trail verification
  • Mutation responses include immediate success/failure indicators
  • Error conditions return granular exception details while preserving FHIR error formats

Advanced Reference Handling​

Inline Resolution​

query {
  Encounter(_id: "789") {
    serviceProvider {
      reference
      _resolvedResource {
        ... on Organization {
          name
          telecom { system value }
        }
      }
    }
  }
}

Security Considerations:

  • Reference resolution requires separate access permissions
  • Resolution depth limited to prevent recursive query explosions
  • Cached resolutions expire after 60 seconds (configurable)

Search Implementation Details​

Parameter Encoding​

# Multiple value syntax
query {
  ObservationConnection(
    code: "http://loinc.org|8310-5&http://loinc.org|8867-4"
  ) {
    edges { resource { ... on Observation { valueQuantity { value } } } }
  }
}

# Modifier syntax
query {
  ConditionList(onset: "ge2023-01-01") {
    resource { ... on Condition { recordedDate } }
  }
}

Implementation Constraints:

  • Maximum 5 combined parameters per search clause
  • Value length limited to 256 characters per parameter
  • URL-encoded special characters automatically decoded

Pagination System​

Cursor Mechanics​

# Initial page request
query {
  MedicationRequestConnection(_count: 25, status: "active") {
    pageInfo {
      nextCursor
      totalCount
    }
    edges { resource { ... on MedicationRequest { dosageInstruction } } }
  }
}

# Subsequent page request
query {
  MedicationRequestConnection(_cursor: "eW91ci1j...ursorLTAwMQ==") {
    pageInfo { hasNextPage }
    edges { resource { ... on MedicationRequest { authoredOn } } }
  }
}

Cursor Features:

  • Opaque string containing search context and position markers
  • 24-hour validity period for pagination continuity
  • Server-side state management for consistent result ordering

Type System Strategy​

FHIR Type Implementation​

# Quantity inheritance example
fragment QuantityDetails on Quantity {
  value
  unit
  system
  code
}

query {
  Observation(_id: "bp") {
    valueQuantity { ...QuantityDetails }
  }
}

Design Rationale:

  • Flattened type hierarchy reduces schema complexity
  • Shared structures maintain FHIR compatibility
  • Type extensions possible through custom scalar fields
  • Schema introspection fully supported for discovery