Composition API Example

In this lesson, we’ll create and retrieve an EHR on the openEHR server. So far, we’ve uploaded a template to the server. But before we can start saving clinical data (compositions), we need an EHR to store that data under. As we discussed previously, the EHR is like the folder in which we need to store all the filled out forms called compositions using the openEHR EHR Composition APIs. So let’s get started.

Creating an EHR

In the postman collection, you’ll find a ‘Create EHR’ request which is a fairly simple POST API request.

POST {{openehrBaseUrl}}/ehr

This is a simple EHR request without any extra details.

Click Send and you should see a 201 Created Status Response and you get a successful response containing an EHR ID.

The EHR ID is the unique identifier for the patient’s record (folder) in the openEHR server.

You must make a note of the EHR ID since we’ll use it in later lessons when creating compositions.

Creating an EHR with subject ID

You can also create an EHR with a Subject ID.

A Subject ID is used to identify a patient in your system. This could be a hospital patient number, a phone number, an NHS number, or a FHIR patient ID.

This is very useful when you want to link the EHR to an existing patient identifier.

So when creating the EHR, you can provide values like:

• subject ID: 1234567
• namespace: NHS_NUMBER The namespace tells the server what kind of identifier this is.

Here’s an example of the request body below:

{
    "_type": "EHR_STATUS",
    "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
    "name": {
        "value": "ehr status"
    },
    "subject": {
        "external_ref": {
            "id": {
                "_type": "GENERIC_ID",
                "scheme": "http://hl7.org/fhir/Patient",
                "value": "1234567"
            },
            "namespace": "NHS number",
            "type": "PERSON"
        }
    },
    "is_modifiable": "true",
    "is_queryable": "true"
}

Click Send, and you should see a 201 Created Status Response and the server will create the EHR and return an EHR ID.

Retrieve an EHR

Since you already have the EHR ID saved, you have to use it to fetch the EHR record.

Select the request ‘Fetch EHR by ehrId’ and replace the ehrId with the ID.

This is done using a GET request

GET {{openehrBaseUrl}}/ehr

Click Send the request and you should see a 200 OK Status Response and you will be able to see the retrieved EHR.

Retrieve an EHR by subject ID

Now say if you want to get your EHR but you are not able to recollect the EHR ID then you can retrieve the EHR based on the subject ID and the namespace.

Select the request ‘Fetch EHR by subjectId’.

This is done using a GET request

GET {{openehrBaseUrl}}/ehr?subject_id={{subjectId}}&subject_namespace={{subjectNamespace}}

Click Send the request and you should see a 200 OK Status Response and you will be able to see the retrieved EHR.

Great! Now with this we have at least one valid EHR created, we can start creating and storing compositions.

Lesson summary

In this lesson, we learned how to create and retrieve EHRs using the openEHR EHR API.

We covered creating a basic EHR (server-generated EHR ID) and also creating an EHR with a subject ID and namespace. Once we had retrieved an EHR by EHR ID and retrieved an EHR by subject ID and namespace.