Resource History
Each time a FHIR resource is created or updated with the Oystehr FHIR API, a new version of that resource is created. The versioned resource is a snapshot of what the FHIR resource looked like at the time it was created or updated. This allows for the history of a resource to be tracked, and for the value of a resource at a given point in time to be checked. It also allows for point-in-time restoration of resources if you need to roll back.
The FHIR standard defines a set of endpoints for retrieving the history of FHIR resources.
Example
For example, we created a Patient with the name Jon Snow, and then updated that patient to include an address called Winterfell. Then we called the resource _history endpoint and received this response:
{
"resourceType": "Bundle",
"type": "history",
"entry": [
{
"fullUrl": "https://testing.fhir-api.zapehr.com/r4/Patient/6e2ef194-3bbd-4702-b51e-abe35f6c4096",
"request": {
"method": "PUT",
"url": "Patient/6e2ef194-3bbd-4702-b51e-abe35f6c4096"
},
"response": {
"status": "200",
"outcome": {
"resourceType": "OperationOutcome",
"id": "ok",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"text": "All OK"
}
}
]
},
"lastModified": "2023-03-24T00:19:07.550Z"
},
"resource": {
"resourceType": "Patient",
"name": [
{
"given": ["Jon"],
"family": "Snow"
}
],
"id": "6e2ef194-3bbd-4702-b51e-abe35f6c4096",
"meta": {
"versionId": "a2be8abc-2ed2-4fde-8ed7-f83cc8603287",
"lastUpdated": "2023-03-24T00:19:07.550Z"
},
"address": [
{
"line": ["Winterfell"]
}
]
}
},
{
"fullUrl": "https://testing.fhir-api.zapehr.com/r4/Patient/6e2ef194-3bbd-4702-b51e-abe35f6c4096",
"request": {
"method": "POST",
"url": "Patient"
},
"response": {
"status": "200",
"outcome": {
"resourceType": "OperationOutcome",
"id": "ok",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"text": "All OK"
}
}
]
},
"lastModified": "2023-03-24T00:18:37.552Z"
},
"resource": {
"resourceType": "Patient",
"name": [
{
"given": ["Jon"],
"family": "Snow"
}
],
"id": "6e2ef194-3bbd-4702-b51e-abe35f6c4096",
"meta": {
"versionId": "bccc4f09-d099-4782-9181-b26e7e6899b4",
"lastUpdated": "2023-03-24T00:18:37.552Z"
}
}
}
],
"total": 2,
"link": [
{
"relation": "self",
"url": "https://testing.fhir-api.zapehr.com/r4/Patient/6e2ef194-3bbd-4702-b51e-abe35f6c4096/_history?_count=100&_offset=0"
},
{
"relation": "first",
"url": "https://testing.fhir-api.zapehr.com/r4/Patient/6e2ef194-3bbd-4702-b51e-abe35f6c4096/_history?_count=100&_offset=0"
}
]
}The history entries are returned in pages.
The maximum number of entries that will be returned in a page is 1000 per request.
The default page size is 100.
The page size can be specified with a _count query parameter.
The page to be returned is specified with a _offset query parameter.
There are also endpoints for getting specific versions of a resource, given a version id. For example, we can call _history/6e2ef194-3bbd-4702-b51e-abe35f6c4096 and receive this response:
{
"resourceType": "Patient",
"name": [
{
"given": ["Jon"],
"family": "Snow"
}
],
"id": "6e2ef194-3bbd-4702-b51e-abe35f6c4096",
"meta": {
"versionId": "bccc4f09-d099-4782-9181-b26e7e6899b4",
"lastUpdated": "2023-03-24T00:18:37.552Z"
}
}History in building applications
The history of resources can be helpful when building applications. It can provide a timeline of a Patient's medical records, and give information about who updated attributes.
Further reading
For more information, refer to the FHIR API documentation (opens in a new tab), and particularly vread (opens in a new tab), history (opens in a new tab), and paging (opens in a new tab).