Skip to main content

Custom Operations

Fire Arrow Server extends the standard FHIR REST API with several custom operations. These follow the FHIR extended operations pattern, using the $ prefix.

$me -- Current User Identity​

Returns the FHIR resource linked to the currently authenticated user. This is the quickest way to verify that authentication and identity resolution are working correctly.

Request:

curl http://localhost:8080/fhir/\$me \
  -H "Authorization: Bearer <your-token>"

Response: The resolved FHIR resource (Patient, Practitioner, RelatedPerson, or Device) as JSON.

$binary-upload -- Upload Binary Files​

Uploads a binary file and stores it in Azure Blob Storage. The returned firearrow:// URL can be embedded in any FHIR resource field. See Binary Storage for the full guide.

Multipart upload:

curl -X POST http://localhost:8080/fhir/\$binary-upload \
  -H "Authorization: Bearer <your-token>" \
  -F "resourceReference=Patient/123" \
  -F "[email protected]"

JSON upload (base64):

curl -X POST http://localhost:8080/fhir/\$binary-upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceReference": "Patient/123",
    "data": "<base64-encoded-content>",
    "contentType": "image/jpeg"
  }'

Response: A FHIR Parameters resource containing the storage URL, content type, and file size:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "url", "valueUrl": "firearrow://container/abc123-def456.jpg" },
    { "name": "contentType", "valueString": "image/jpeg" },
    { "name": "size", "valueInteger": 204800 }
  ]
}

$generate-durable-token -- Create a Long-Lived API Token​

Generates a durable API token for programmatic access to a specific FHIR resource. Durable tokens are prefixed with fa_ and remain valid until explicitly revoked.

Request:

curl -X POST http://localhost:8080/fhir/Patient/123/\$generate-durable-token \
  -H "Authorization: Bearer <your-token>"

Response:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "token", "valueString": "fa_abc123..." }
  ]
}

Use the token in subsequent requests:

curl http://localhost:8080/fhir/Patient/123 \
  -H "Authorization: Bearer fa_abc123..."

$generate-one-time-token -- Create a Single-Use Token​

Generates a one-time API token that is invalidated after its first use. One-time tokens are prefixed with fo_ and are ideal for secure handoffs like magic links or single-use downloads.

Request:

curl -X POST http://localhost:8080/fhir/Patient/123/\$generate-one-time-token \
  -H "Authorization: Bearer <your-token>"

Response:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "token", "valueString": "fo_xyz789..." }
  ]
}

$redeem-token -- Exchange a Token for a Session​

Redeems a durable or one-time API token, returning the identity associated with it. This is useful for validating tokens from external systems.

Request:

curl -X POST http://localhost:8080/fhir/\$redeem-token \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      { "name": "token", "valueString": "fa_abc123..." }
    ]
  }'

Response: The FHIR resource (Patient, Practitioner, etc.) associated with the token.

$subscribe-due-events -- Subscribe to CarePlan Events​

Creates a webhook subscription that is triggered when scheduled CarePlan activities become due. This is a convenience wrapper around the FHIR Subscription resource -- see CarePlan Events for the full guide.

Request:

curl -X POST http://localhost:8080/fhir/CarePlan/789/\$subscribe-due-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      { "name": "endpoint", "valueUrl": "https://your-app.example.com/webhooks/careplan" }
    ]
  }'

Response: The created FHIR Subscription resource, including its id and end date (the subscription TTL).

PlanDefinition $apply -- Apply with Timezone Support​

Fire Arrow Server enhances the standard FHIR PlanDefinition/$apply operation with timezone-aware scheduling. When applying a PlanDefinition that contains timing-based activities, you can specify the patient's timezone to ensure activities are scheduled at the correct local times.

Request:

curl -X POST http://localhost:8080/fhir/PlanDefinition/plan-1/\$apply \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      { "name": "subject", "valueString": "Patient/123" },
      { "name": "timezone", "valueString": "Europe/Zurich" }
    ]
  }'

Response: The resulting CarePlan resource with activities scheduled according to the PlanDefinition, adjusted for the specified timezone.

Key behaviors of the enhanced $apply:

  • Timezone-aware scheduling -- timing-based activities respect the patient's local timezone
  • Extension propagation -- extensions on PlanDefinition actions are carried through to the resulting CarePlan activities
  • Activity detail mapping -- PlanDefinition action definitions are mapped to CarePlan activity details

Authorization for Custom Operations​

Custom operations require specific authorization rules. Add rules for the operations your clients need:

fire-arrow:
  authorization:
    validation-rules:
      - client-role: "Patient"
        resource: "Patient"
        operation: "me"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Binary"
        operation: "binary-upload"
        validator: "PatientCompartment"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "generate-durable-token"
        validator: "LegitimateInterest"
      - client-role: "Practitioner"
        resource: "CarePlan"
        operation: "subscribe"
        validator: "LegitimateInterest"