Edit

History management for Azure API for FHIR

  • Article

Important

Azure API for FHIR will be retired on September 30, 2026. Follow the migration strategies to transition to Azure Health Data Services FHIR service by that date. Due to the retirement of Azure API for FHIR, new deployments won't be allowed beginning April 1, 2025. Azure Health Data Services FHIR service is the evolved version of Azure API for FHIR that enables customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure services.

History in FHIR gives you the ability to see all previous versions of a resource. History in FHIR can be queried at the resource level, type level, or system level. The HL7 FHIR documentation has more information about the history interaction. History is useful in scenarios where you want to see the evolution of a resource in FHIR or if you want to see the information of a resource at a specific point in time.

All past versions of a resource are considered obsolete and the current version of a resource should be used for normal business workflow operations. However, it can be useful to see the state of a resource as a point in time when a past decision was made.

The query parameter _summary=count and _count=0 can be added to _history endpoint to get count of all versioned resources. This count includes soft deleted resources.

Azure API for FHIR allows you to manage history with

  1. Disabling history To disable history, one time support ticket needs to be created. After disable history configuration is set, history isn't created for resources on the FHIR server. Resource version is incremented. Disabling history won't remove the existing history for any resources in your FHIR service. If you're looking to delete the existing history data in your FHIR service, you must use the $purge-history operation.

  2. Purge History: $purge-history is an operation that allows you to delete the history of a single FHIR resource. This operation isn't defined in the FHIR specification.

Overview of purge history

The $purge-history operation was created to help with the management of resource history in Azure API for FHIR. It's uncommon to need to purge resource history. However, it's needed in cases when the system level or resource level versioning policy changes, and you want to clean up existing resource history.

Since $purge-history is a resource level operation versus a type level or system level operation, you'll need to run the operation for every resource that you want remove the history from.

Examples of purge history

To use $purge-history, you must add /$purge-history to the end of a standard delete request. The template of the request is:

DELETE <FHIR-Service-Url>/<Resource-Type>/<Resource-Id>/$purge-history

For example:

DELETE https://workspace-fhir.fhir.azurehealthcareapis.com/Observation/123/$purge-history

Next steps

In this article, you learned how to purge the history for resources in Azure API for FHIR. For more information about Azure API for FHIR, see

Supported FHIR features

FHIR REST API capabilities for Azure API for FHIR

FHIR® is a registered trademark of HL7 and is used with the permission of HL7.