Skip to main content

FHIR API Request Guide

API Fundamentals​

Service Endpoints​

Development: https://localhost:8000/graphql
Production:  https://<your-domain>/graphql

Authentication Requirements:

Authorization: Bearer <JWT_TOKEN>

Environment Setup​

# Verify connectivity
curl -H "Authorization: Bearer $TOKEN" $ENDPOINT \
  -d '{"query":"{ Me { reference } }"}'

Core Request Patterns​

Identity Verification​

query IdentityCheck {
  Me {
    reference  # Returns "ClientRole/ClientID"
    resourceType
  }
}

Usage Scenario: Validate authentication context before sensitive operations

Resource Operations​

Create Resources​

mutation CreatePatient($input: PatientCreateInput!) {
  CreatePatient(resource: $input) {
    id
    meta { versionId lastUpdated }
  }
}

Input Validation:

  • Requires minimum demographic fields
  • Rejects duplicate identifiers
  • Auto-generates missing required fields

Read Operations​

Single Resource Retrieval​

query FetchPatient($id: ID!) {
  Patient(id: "c6a5ef32-72b7-45e1-8faa-9e89807b5192") {
    name { given family }
    address { line city }
  }
}

Search Methods​

# Basic search (PatientList)
query {
  PatientList(name: "Smith", birthdate: "ge2000-01-01") {
    id
    name { given family }
  }
}

# Paginated search (PatientConnection)
query {
  PatientConnection(name: "John", _count: 25) {
    pageInfo { totalCount nextCursor }
    edges {
      node {
        id
        name { given family }
      }
    }
  }
}

Update Operations​

mutation UpdateContact($id: ID!, $input: PatientUpdateInput!) {
  UpdatePatient(id: $id, resource: $input) {
    meta { lastUpdated }
    telecom { system value }
  }
}

Concurrency Control:

  • Uses meta.versionId for optimistic locking
  • Returns 412 Precondition Failed on version mismatch

Delete Operations​

mutation RemovePatient($id: ID!) {
  DeletePatient(id: "12345") {
    issue {
      severity
      code
      details { text }
    }
  }
}

Permanent Deletion:

  • Requires forceDelete parameter for hard deletes
  • Default behavior: Soft delete with tombstone record

Search Implementation​

Complex Queries​

query AdvancedSearch {
  PatientConnection(
    name: "smith",
    _tag: "research-study-45",
    _lastUpdated: "ge2023-01-01"
  ) {
    edges {
      node {
        id
        name { family given }
        extension(url: "http://hl7.org/fhir/StructureDefinition/patient-congregation") {
          valueString
        }
      }
    }
  }
}

Search Modifiers:

  • :exact for precise matching
  • :missing for null value checks
  • :contains for partial text matches

Development Tools​

Interactive Playground​

Access URL: https://localhost:8000/playground

Header Configuration:

{
  "Authorization": "Bearer eyJhbGciOiJIUz...",
  "X-Request-ID": "custom-correlation-id"
}

Playground Features:

  • Schema documentation sidebar
  • Query variable injection
  • Response formatting presets
  • Request history persistence

API Client Configuration​

Postman Setup Template​

Collection Variables:

{
  "base_url": "{{environment}}/graphql",
  "token": "{{jwt_secret}}"
}

Sample Request:

query GetRecentPatients {
  PatientConnection(_sort: "-_lastUpdated", _count: 5) {
    edges {
      node {
        id
        name { given family }
      }
    }
  }
}

Security Operations​

Production Hardening​

# settings.py
GRAPHQL_PLAYGROUND = False  # Disable in production
INTROSPECTION_ENABLED = False  # Disable schema introspection
RATE_LIMIT = "1000/hour"  # Global rate limiting

Secret Rotation Schedule:

  • JWT Signing Key: 90 days
  • Database Encryption Keys: 365 days
  • API Tokens: 30 days

Operational FAQ​

Data Handling​

Q: How are extensions managed?
A: Extensions persist in dedicated fields without altering core resource structure

Q: File upload limitations?
A: 256MB maximum with automatic virus scanning

Compliance​

Q: Audit log retention?
A: 7-year retention with WORM storage

Interface Support​

Q: REST API availability?
A: Full REST endpoint parity at /api/fhir/r4/