health-fhir-api-design

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: health-fhir-api-design
description: Design FHIR R4 API interactions — search queries, operations ($), validation, workflow patterns, and custom SearchParameter / OperationDefinition resources. The user provides requirements; the skill recommends a concrete R4 approach with trade-offs.
---

# FHIR R4 API Design

## When To Use

Invoke to design or review FHIR R4 API interactions — search queries, operations, validation strategy, and workflow patterns. Use when you need a concrete interaction design with trade-offs documented. This skill handles the interaction layer; use `health-fhir-modeling` first for the modeling layer.

## Overview

Help users design concrete FHIR R4 (v4.0.1) API interactions for their requirements. The user describes **what they need** — the skill recommends **how to achieve it** using the R4 RESTful API, covering resource selection, search construction, operations, validation strategy, and workflow coordination.

This skill is advisory only. It does not modify repository files, application code, or server configuration.

This skill is grounded in the HL7 FHIR R4 specification at `https://hl7.org/fhir/R4/`.

---

## Modes

### Mode: design (default)

#### Intent

Take a user's requirements and produce an actionable FHIR R4 API design.

#### Steps

1. **Clarify requirements** — ask what data the user needs to read, write, or coordinate, which actors are involved, and what systems participate.

2. **Map to R4 resources** — identify which FHIR R4 resources represent the domain entities. Prefer standard resources and US Core / IPS profiles before custom structures. Reference `https://hl7.org/fhir/R4/resourcelist.html`.

3. **Design the interactions** — for each requirement, recommend the appropriate R4 API pattern:

   **Search queries** (the most common and trickiest area):
   - Identify the correct search parameter names, types (token, reference, date, string, quantity, composite, uri, special), and modifiers (`:exact`, `:contains`, `:missing`, `:not`, `:text`, `:in`, `:not-in`, `:below`, `:above`, `:of-type`, `:identifier`)
   - Use prefixes for date/number/quantity ranges (`eq`, `ne`, `gt`, `lt`, `ge`, `le`, `sa`, `eb`, `ap`)
   - Show chained parameters (`patient.name`) and reverse chaining (`_has`) when needed
   - Use `_include` / `_revinclude` (with `:iterate` when needed) to pull related resources
   - Use composite parameters (joined with `$`) for multi-axis searches like component-code-value-quantity
   - Show AND (repeated parameter) vs OR (comma-separated) semantics
   - Address missing-data safety: `clinical-status:missing=true` pattern for open-world queries like AllergyIntolerance
   - Note `Prefer: handling=strict` vs `handling=lenient` for unknown/unsupported parameter behavior
   - Reference `https://hl7.org/fhir/R4/search.html`

   **Operations ($)**:
   - Identify when a standard operation fits: `$validate`, `$expand`, `$validate-code`, `$translate`, `$lookup`, `$subsumes`, `$everything`, `$match`, `$document`, `$apply`, `$evaluate-measure`, `$lastn`, `$stats`, `$process-message`
   - Explain invocation: POST with Parameters resource, or GET with URL params (only for affectsState=false with primitive params)
   - Distinguish system-level (`[base]/$op`), type-level (`[base]/[type]/$op`), and instance-level (`[base]/[type]/[id]/$op`) scoping
   - Reference `https://hl7.org/fhir/R4/operations.html` and `https://hl7.org/fhir/R4/operationslist.html`

   **Validation**:
   - `$validate` operation: `POST [base]/[type]/$validate?profile=[url]` — validates structure, cardinality, value domains, bindings, invariants, and profile conformance
   - Distinguish 400 (failed basic FHIR rules) from 422 (failed business rules / profiles)
   - Note validation trade-offs per Postel's law: strictness in sending, liberality in receiving
   - Profile-based validation, CapabilityStatement validation, and the FHIR Validator jar
   - Reference `https://hl7.org/fhir/R4/validation.html`

   **Workflow coord