FHIR APIs define a standard approach for exchanging healthcare information through RESTful requests and responses. Each operation, whether retrieving a patient record or submitting a lab result, follows the same predictable pattern based on HTTP methods.
Iguana provides a practical way to implement FHIR operations in real systems. Its scripting environment lets developers connect to FHIR servers, send requests, and process responses using concise, readable code.
The examples below are intentionally simple: they focus on illustrating FHIR API behaviour rather than replicating full production implementations. Real-world integrations often include additional layers such as authentication flows, data validation, and error handling, all of which Iguana supports.
A FHIR server is the system that stores and serves healthcare resources such as Patient, Observation, or Encounter records. Client applications communicate with the server using standard HTTP requests.
In Iguana, this is handled through the net.http module, which provides REST methods corresponding to FHIR's CRUD actions:
net.http.get{} -- Retrieve data (Read)
net.http.post{} -- Add new data (Create)
net.http.put{} -- Modify existing data (Update)
net.http.delete{} -- Remove data (Delete)
The following example shows a simple GET request to retrieve a Patient record:
-- Retrieve a Patient resource by ID
local Response = net.http.get{
url = 'https://fhirserver.example.com/Patient/12345',
auth = { username = 'user', password = 'pass' },
live = true
}
This request sends an authenticated call to the FHIR server and returns the Patient resource in JSON format. Although this example is minimal, the same structure applies to more advanced integrations that include OAuth tokens, request retries, or complex validation logic.
FHIR defines four standard actions (CRUD): Create, Read, Update, and Delete. Each maps directly to an HTTP method. The following examples illustrate how these operations work in practice and how Iguana's scripting environment can be used to implement them.
-- Read a Patient resource, then parse the JSON response
local Response = net.http.get{
url = 'https://fhirserver.example.com/Patient/12345',
auth = { username = 'user', password = 'pass' },
live = true
}
-- Parse the FHIR JSON response into a Lua table for easy access
local Data = json.parse{ data = Response }
-- Access the patient's family name from the parsed data
trace(Data.name[1].family)
Note: The json module in Iguana handles conversion between Lua tables and JSON structures, allowing developers to work with FHIR data more naturally.
-- Create a new Observation resource
local Resource = {
resourceType = 'Observation',
status = 'final',
code = { text = 'Body Temperature' },
valueQuantity = { value = 37.5, unit = 'deg C' }
}
-- Send the POST request with the JSON body
net.http.post{
url = 'https://fhirserver.example.com/Observation',
body = json.serialize{ data = Resource },
content_type = 'application/json',
live = true
}
Note: The json.serialize function in Iguana converts the Lua table into JSON before transmission, matching the format expected by FHIR servers.
Equivalent JSON payload:
{
"resourceType": "Observation",
"status": "final",
"code": { "text": "Body Temperature" },
"valueQuantity": { "value": 37.5, "unit": "deg C" }
}
-- Update an existing Patient record with new address information
local Updated = {
resourceType = 'Patient',
id = '12345',
address = { { line = { '123 Main St' }, city = 'Toronto' } }
}
-- Convert the Lua table to JSON and send a PUT request
net.http.put{
url = 'https://fhirserver.example.com/Patient/12345',
body = json.serialize{ data = Updated },
content_type = 'application/json',
live = true
}
-- Delete an Observation resource by ID
net.http.delete{
url = 'https://fhirserver.example.com/Observation/9876',
auth = { username = 'user', password = 'pass' },
live = true
}
These examples demonstrate how FHIR API interactions follow consistent patterns across all resource types. In production systems, these same operations would be extended with additional safeguards and logic to ensure data integrity and security.
When a FHIR server responds to a request, it provides valuable context beyond the data itself. Each HTTP response includes:
These elements can be captured and inspected directly within Iguana's development environment.
-- Capture body, status code, and headers from the FHIR response
local Response, Code, Headers = net.http.get{
url = 'https://fhirserver.example.com/Patient/12345',
auth = { username = 'user', password = 'pass' },
live = true
}
-- Inspect the returned information
trace(Code, Headers, Response)
-- Parse and review specific fields from the JSON body
local Data = json.parse{ data = Response }
trace(Data.resourceType, Data.id)
This visibility allows developers to verify request behavior and troubleshoot issues efficiently, which is essential for managing API-based integrations.
FHIR servers typically require secure authentication before allowing data access, either through Basic Authentication or OAuth 2.0.
Basic Authentication example:
auth = { username = 'api_user', password = 'api_pass' }
Basic Authentication is simple to implement but less secure for production use, as it involves sending static credentials with each request.
In production environments, OAuth 2.0 is more common. It provides stronger security by using time-limited access and refresh tokens instead of static credentials. The setup is more involved, as it requires an authorization server to validate client credentials, issue tokens, and handle token refresh cycles. This additional complexity allows for secure, automated sessions that are better suited to real-world healthcare integrations.
Iguana can be configured to handle both authentication methods, allowing developers to connect securely to production-grade FHIR servers. Prebuilt adapters are available for common EHRs such as Epic, Athenahealth, and eClinicalWorks, each implementing the required authentication and request patterns for their respective FHIR APIs.
The examples in this section show FHIR operations at their simplest, providing a clear understanding of the structure and logic behind API interactions. Real-world implementations extend these concepts to include additional requirements such as authentication workflows, data validation, error handling, and audit logging.
Iguana's architecture is designed to scale from these foundational interactions to complex, production-level integrations. The same REST and JSON-based principles shown here apply to multi-system deployments, large message volumes, and EHR-specific interfaces.
After exploring how to use FHIR APIs in real workflows, the next step is to see how these integrations extend to enterprise EHR systems like Epic, Athenahealth, and eClinicalWorks.
Continue reading: Connecting to EHR Systems Using FHIR APIs →
