Resource History

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"
        }
      }
    }
  ]
}

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) and history (opens in a new tab).