FHIR

Resources and the web API

FHIR describes health data as resources. The standard calls the resource “the basic building block”. A resource can be a patient, an observation such as a blood pressure reading, an allergy, a medication order or a claim.¹ Each resource has a type, an id and a version. Systems usually send it as JSON, with the media type application/fhir+json.

Systems work with resources through a short list of actions on web addresses like /Observation/123. They can read, read one version, search, create, update, patch, delete and see the history. They can also send several actions at once in a batch or a transaction.² These are plain web requests. So any program that can send a request can write to a FHIR server, and that now includes AI agents.

Versions: R4, R5 and R6

FHIR has had several releases. R4 came out on 27 December 2018, and its correction, 4.0.1, on 30 October 2019. R5 followed on 26 March 2023, and R6 is being voted on.⁵ Most live servers, national guides and vendor APIs still use R4. So a project started today usually targets 4.0.1. The actions are mostly the same across releases. What changes is the shape of some resources.

How an AI agent writes to FHIR

An agent rarely talks to a hospital’s FHIR server on its own. A gateway or an app holds the keys, usually a sign-in the server’s owner set up for it. The agent asks that app to run a tool, such as “create an Observation”.

What an agent may write depends on the server. Epic’s public R4 test server, for example, lists create for allergies and conditions, and create and update for observations, documents and service requests. It lists only read and search for medication orders. Each customer’s setup can differ.³

Where a write can say one thing and store another

FHIR’s own rules leave a gap between what an agent reports and what the server saved:

• Create only if new. A create sent with If-None-Exist that matches one existing resource is ignored. The server answers 200 OK and creates nothing.² An agent that reads “200” as “created” reports a write that never happened.
• The saved copy is optional. A client can ask the server to send back what it saved, using the Prefer header. But servers only “SHOULD” do it.² So the answer may not show what was saved.
• Version checks. An update sent with If-Match and an old version gets 412 Precondition Failed. Nothing is written.² An agent that just tries again can overwrite someone else’s change.
• Errors after the fact. A timeout or a server error doesn’t say whether the write went through. Only reading the resource again tells you.

The safe habit is simple. Read the resource back after every write, and compare it with what the agent meant to save. Our FHIR write benchmark runs these cases on a real server and shows where a read-back catches them and where it misses, misses first. The method is a read-back check.

FHIR and audit

FHIR also has resources for recording what happened. AuditEvent is “a record of an event made for purposes of maintaining a security log”. Provenance describes who and what took part in making a resource.⁴⁸ With them, a server, or a tool in front of it, can describe agent actions in a format other health systems already read. See audit trail for AI in healthcare.