History and Versions

One powerful feature of a FHIR server is that it maintains a complete version history of every resource. This means you can track how a resource has changed over time, see all past versions, and even view the history of the entire server.

Let’s go through how to use the _history operation at different levels: resource, type, and system.

Resource-Level History

Let’s say you have a Patient resource with multiple updates. Every time you perform a PUT request, the version ID of that patient is incremented. For example, a patient named John may currently be on version 3. To see the full history of this patient:

GET [base]/Patient/[id]/_history

This returns a Bundle listing all versions of that patient:

• Version 1 → the original record.
• Version 2 → an update.
• Version 3 → the current version.

Each version can be retrieved individually if you want to inspect exactly what changed.

Type-Level History

You can also get the history of all resources of a particular type. For example, to see all changes that have ever happened to any patient:

GET [base]/Patient/_history

This returns a chronological list of modifications (create, update, delete) for every Patient on the server.

System-Level History

The most extensive history query is at the root level:

GET [base]/_history

This retrieves the entire server’s change log, across all resource types, Patients, Practitioners, Observations, and more.

You’ll see every operation (create, read, update, delete) recorded in order. This effectively gives you a timeline of the server’s activity from the very beginning.

Controlling the Results

Like other searches, history queries can be refined:

Use _count to control how many records are returned.

GET [base]/_history?_count=2000

Then combine history with search parameters to filter specific subsets.

Deleted resources also appear in history results, so you get a complete audit trail.

Conclusion

Every update, delete, or creation is logged by default (especially in servers like HAPI FHIR). This makes _history a powerful tool for tracking changes, ensuring consistency, and meeting regulatory requirements.

Next time you update a resource, try appending /_history to see how FHIR tracks its journey.