fhir‑client

A lightweight, opinionated Python client for working with FHIR servers via the REST API.

---

📚 Table of Contents

• What is fhir‑client?
• Key Features
• Installation
• Getting Started
• Examples
  • Basic CRUD
  • Search & Filtering
  • Authentication
• Contributing
• License
• Acknowledgements

---

🔍 What is fhir‑client?

fhir-client is a minimal wrapper around the FHIR REST API.
It handles:

• Standard CRUD operations (GET, POST, PUT, DELETE)
• Automatic JSON serialization/deserialization
• Optional authentication (Basic Auth, OAuth2)

Designed for developers who want to get started quickly without the overhead of a full‑blown SDK.

---

✨ Key Features

Feature	Description
Simple API	FHIRClient exposes high‑level methods that map directly to FHIR operations.
Configurable	Base URL and authentication can be set globally or per request.

---

📦 Installation

# From PyPI
pip install fhir-server-client

Developed and tested on Python 3.12

---

🚀 Getting Started

from fhir_client.client import FhirClient

# Create a client pointing at the HAPI FHIR demo server
client = FhirClient(base_url="https://hapi.fhir.org/baseR4")

# Perform a GET request for a Patient
patient = client.get("Patient", _id=123)
print(patient)

# Or use the generic GET method
patients = client.get("/Patient")
print(patients)

---

📚 Examples

Below are a few common use cases. Feel free to copy‑paste and adapt.

📦 Basic CRUD

# CREATE a new Patient
new_patient = {
    "resourceType": "Patient",
    "name": [{"family": "Doe", "given": ["John"]}],
    "gender": "male",
    "birthDate": "1974-12-25"
}
created = client.post("Patient", data=new_patient)
print("Created patient ID:", created["id"])

# READ the newly created Patient
patient = client.get("Patient", _id=created["id"])
print(patient)

# UPDATE the Patient
patient["name"][0]["given"] = ["Jonathan"]
updated = client.put("Patient", id=created["id"], data=patient)
print("Updated patient:", updated)

# DELETE the Patient
client.delete(resource_type="Patient", _id=patient["id"])
print("Patient deleted.")

🔍 Search & Filtering

# Search for patients named "John" with a minimum age of 18
results = client.get("Patient", name="John", birthdate="ge1975-01-01")

for patient in results["entry"]:
    print(patient["resource"]["id"], patient["resource"]["name"][0]["given"])

# Checking for and getting self, next and previous links
if client.has_self():
    self_link = client.self

if client.has_next():
    next_link = client.next

if client.has_previous():
    previous_link = client.previous

The get method accepts search parameters as python keyword arguments. Those are appended in the FHIR Search Query

🔐 Authentication

# Using Basic Auth
from fhir_client.auth import FhirAuth

auth = FhirAuth().set_basic_auth("username", "password")
client = FHIRClient("https://fhir.example.com", auth=auth)

# Using OAuth2 (client credentials flow)
from fhir_client.auth import FhirAuth

auth = FhirAuth().set_o_auth(
    auth_url="https://auth.example.com/token",
    client_id="client-id",
    client_secret="client-secret"
)
client = FHIRClient(base_url="https://fhir.example.com", auth=auth)

---

🤝 Contributing (WORK IN PROGRESS)

We love contributions! Please read our CONTRIBUTING.md for guidelines on coding style, testing, and pull requests.

Steps to get started

1. Fork the repo and clone it locally.
2. Create a new branch (git checkout -b feature/foo).
3. Write tests for your change.
4. Run the test suite (pytest).
5. Submit a pull request.

---

📄 License

MIT © 2026

See the LICENSE file for details.

---

🙏 Acknowledgements

• HL7 FHIR
• HAPI FHIR
• Contributors who opened issues and pull requests

---

Happy coding! 🎉