FHIR REST API Overview

Fire Arrow Server implements the HL7 FHIR RESTful API specification, providing full CRUD operations on all supported FHIR resource types. Use the REST API for creating, updating, and deleting resources, as well as for standard FHIR search and interactions. For read-heavy workloads, consider the GraphQL API, which lets you fetch exactly the fields you need in a single request.

Base URL

All FHIR REST endpoints share a common base URL:

http://localhost:8080/fhir

In production, this will be your server's public URL followed by /fhir.

Capability Statement

The server's capability statement describes all supported resources, search parameters, and operations:

curl http://localhost:8080/fhir/metadata \
  -H "Accept: application/fhir+json"

This is the standard FHIR CapabilityStatement resource and is useful for client auto-discovery.

Content Types

Fire Arrow Server supports both JSON and XML representations:

Content-Type	Format
application/fhir+json	JSON (recommended)
application/fhir+xml	XML

Set the Content-Type header on write requests and the Accept header on read requests. If omitted, the server defaults to JSON.

CRUD Operations

Read

Fetch a single resource by type and ID:

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

Search

Search for resources using FHIR search parameters:

curl "http://localhost:8080/fhir/Patient?name=Smith&birthdate=1990-01-01" \
  -H "Authorization: Bearer <your-token>"

The response is a FHIR Bundle of type searchset containing matching resources.

Create

Create a new resource with a POST request:

curl -X POST http://localhost:8080/fhir/Patient \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Patient",
    "name": [{ "family": "Smith", "given": ["Jane"] }],
    "birthDate": "1990-01-01",
    "gender": "female"
  }'

A successful create returns 201 Created with a Location header pointing to the new resource.

Update

Replace an existing resource with a PUT request:

curl -X PUT http://localhost:8080/fhir/Patient/123 \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Patient",
    "id": "123",
    "name": [{ "family": "Smith", "given": ["Jane", "Marie"] }],
    "birthDate": "1990-01-01",
    "gender": "female"
  }'

Delete

Remove a resource:

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

Authorization

REST API operations map to authorization operations in your validation rules:

HTTP Method	Authorization Operation
GET (single resource)	read
GET (search)	search
POST (create)	create
PUT (update)	write
DELETE (delete)	delete

Swagger UI

Fire Arrow Server includes a built-in Swagger UI that lets you browse every endpoint, inspect request and response schemas, and execute requests interactively:

http://localhost:8080/fhir/swagger-ui/index.html

The OpenAPI specification backing the Swagger UI is available at:

http://localhost:8080/fhir/api-docs

Use this to generate type-safe client libraries with tools like openapi-generator.

Next Steps

See Custom Operations for Fire Arrow Server's extended operations beyond standard FHIR CRUD, including $me, $binary-upload, API token generation, and CarePlan event subscriptions.