FHIR REST API implementation

This skill provides guidance for implementing FHIR RESTful APIs according to the HL7 FHIR specification (R4/R5).

URL structure

All FHIR REST URLs follow the pattern:

[base]/[type]/[id]

• [base]: Service base URL (e.g., https://fhir.example.org/r4)
• [type]: Resource type (e.g., Patient, Observation)
• [id]: Logical resource ID

URLs are case-sensitive and use UTF-8 encoding.

Core operations

For detailed specifications of each operation, see references/operations.md.

Content negotiation

MIME types

Use the Accept header for response format and Content-Type for request body format.

The _format query parameter overrides Accept when clients cannot set headers.

FHIR version

Specify version via MIME type parameter:

Accept: application/fhir+json; fhirVersion=4.0

Version mappings: 1.0 (R2), 3.0 (R3), 4.0 (R4), 4.3 (R4B), 5.0 (R5).

Required headers

Request headers

Response headers

Versioning and optimistic locking

FHIR uses weak ETags for version tracking:

1. Server returns ETag: W/"[versionId]" with responses
2. Client sends If-Match: W/"[versionId]" with updates
3. Server returns 412 Precondition Failed if version mismatch

Implement version-aware updates when CapabilityStatement.rest.resource.versioning is versioned-update.

Error handling

Return OperationOutcome resources for all errors:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "diagnostics": "Patient.birthDate: Invalid date format"
        }
    ]
}

Status codes

Prefer header

Control response content with Prefer:

For async operations, use Prefer: respond-async to get 202 Accepted with status polling URL.

Implementation checklist

Server implementations should:

1. Implement CapabilityStatement at /metadata
2. Support content negotiation (JSON at minimum)
3. Return proper ETags for versioned resources
4. Include Location header on create/update
5. Return OperationOutcome for all errors
6. Support _format parameter fallback
7. Honour Prefer header for response content

References

• operations.md: Detailed operation specifications
• search.md: Search parameter and result handling
• batch-transaction.md: Batch and transaction processing