> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ferrum.thalamiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Overview of the Ferrum REST API

## Welcome

The **Ferrum** provides a complete RESTful API implementation compliant with the [FHIR R4 specification](https://www.hl7.org/fhir/R4/http.html). All endpoints are prefixed with `/fhir` and follow FHIR's standard URL patterns.

## Base URL

All API endpoints are relative to the base URL. The API playground supports multiple server environments:

* **Local Development**: `http://localhost:8080/fhir` (default port)
* **Production**: Configure your production server URL in the OpenAPI spec

You can switch between servers using the dropdown in the API playground on each endpoint page.

## FHIR Compliance

This server implements the FHIR RESTful API specification, including:

* **CRUD Operations**: Create, Read, Update, Delete, and Patch resources
* **Search**: System-level, type-level, and compartment-based search
* **History**: System, type, and resource-level history with versioning
* **Batch & Transaction**: Batch processing and transaction support
* **Operations**: System, type, and instance-level FHIR operations
* **Metadata**: Capability statement describing server capabilities

## URL Handling

Per FHIR specification:

* **Case Sensitivity**: All URLs and IDs are case-sensitive
  * `/Patient/123` ≠ `/patient/123`
* **Trailing Slashes**: Both forms are supported (with and without trailing slash)
  * `/Patient` and `/Patient/` both work
* **UTF-8 Encoding**: URLs are UTF-8 encoded and decoded automatically
  * `/Patient/abc%20def` → `/Patient/abc def`
  * `/Patient/%E4%B8%AD` → `/Patient/中`

## HTTP Methods

The server supports standard HTTP methods:

* `GET` - Read resources and perform searches
* `POST` - Create resources, batch operations, and search
* `PUT` - Update resources (must include full resource)
* `PATCH` - Partial update of resources
* `DELETE` - Delete resources
* `HEAD` - Check resource existence without body

## Response Formats

The server supports multiple content types:

* `application/fhir+json` (default)
* `application/fhir+xml`
* `application/json`
* `application/xml`

Use the `Accept` header to specify your preferred format, and `Content-Type` header when sending data.

## OpenAPI Specification

A complete OpenAPI 3.1.0 specification is available for this API. You can use it with API clients, testing tools, and documentation generators.

<Card title="OpenAPI Specification" href="https://github.com/thalamiq/ferrum/blob/main/docs/api-reference/openapi.json">
  View the complete OpenAPI specification file
</Card>

The OpenAPI spec includes:

* All FHIR REST endpoints
* Request/response schemas
* Authentication requirements
* Error responses
* Search parameters
* Server configurations for API playground

### API Playground

Each endpoint page includes an interactive API playground where you can:

* Test API calls directly from the documentation
* Switch between different server environments (local, staging, production)
* See request/response examples
* Try different parameters and request bodies

### Using the OpenAPI Spec

You can import this specification into:

* **API Clients**: Postman, Insomnia, HTTPie
* **Code Generators**: OpenAPI Generator, Swagger Codegen
* **Testing Tools**: REST Assured, Karate
* **Documentation Tools**: Swagger UI, Redoc

To customize the server URLs for your environment, edit the `servers` array in `api-reference/openapi.json`.