API - Get Document List

This API retrieves the list of documents from AWS DynamoDB

Scope

This transaction involves the requestor sending a GET request to the FHIR service to retrieve a list of DocumentReference resources based on certain parameters such as the source system, document category, etc.

Each DocumentReference resource contains an attachment URL of one of the following in root relative path format:

  • binary file (for example /Binary/eimr-ttsh-U2FsdGVkX18KFMPcFnDTG2XO1pP0KO9GEZwFJlnU6bc=:d428e7db-2964-44be-855b-00c7475da6cb)
  • composition json file (for example /Composition/eimr-ttsh-U2FsdGVkX18KFMPcFnDTG2XO1pP0KO9GEZwFJlnU6bc=:d428e7db-2964-44be-855b-00c7475da6cb).

Upon successful retrieval, the FHIR Service returns an HTTP response code (i.e 2xx) and a Bundle containing a collection of DocumentReference resources.

For unsuccessful retrieval, the FHIR Service returns an HTTP response code (i.e 4xx or 5xx) and an OperationOutcome resource.

Interaction Diagram

get-document-list

Specification

The Get Document List FHIR specification is based on the HL7 FHIR R5 extended operation. (Ref: https://www.hl7.org/fhir/operations.html)

Invocations

URL: [base]/DocumentReference/$get-document-list

This operation does NOT change content

Parameters (In)

NameCardinalityTypeDocumentation
_source1..1string
author1..1string
category1..1string
subject1..1string
_count0..1integer
_sort0..1string
_skip0..1boolean
ct0..1string

Return Values (Out)

NameCardinalityTypeDocumentation
document-list1..1Bundle

The Get Document List Request will retrieve a list of documents from AWS DynamoDB in the form of a Bundle from a server-assigned location. The get interaction is performed by an HTTP GET command

Example

Type Value
Method GET
Headers Content-Type: application/fhir+json
URL [base]/DocumentReference/$get-document-list
Message Body 
{
    "resourceType": "Parameters",
    "parameter":  [
        {
            "name": "_source",
            "valueString": "http://ihis.sg/source-system/erx"
        },
        {
            "name": "author",
            "valueString": "ttsh"
        },
        {
            "name": "category",
            "valueString": "discharge-summary"
        },
        {
            "name": "subject",
            "valueString": "U2FsdGVkX1-eXowTVO3diSIV_xq8kIME4BxcsYYrh-s="
        },
        {
            "name": "_count",
            "valueInteger": 10
        },
        {
            "name": "_sort",
            "valueString": "source-institution"
        }
    ]
}

Message Response

Depending on the HTTP Status Code, the following resources will be sent back to the requestor.

HTTP Status Code Example
201 Created 
{
    "resourceType": "Bundle",
    "id": "0HN5M0IG822AR:00000005",
    "meta": {
        "lastUpdated": "2024-08-01T14:29:55.949+08:00"
    },
    "type": "collection",
    "entry":  [
        {
            "fullUrl": "urn:uuid:docref1",
            "resource": {
                "resourceType": "DocumentReference",
                "id": "1",
                "meta": {
                    "source": "http://ihis.sg/source-system/erx"
                },
                "identifier":  [
                    {
                        "system": "http://ihis.sg/identifier/ccda",
                        "value": "guid"
                    }
                ],
                "status": "current",
                "docStatus": "final",
                "type": {
                    "coding":  [
                        {
                            "system": "http://ihis.sg/cs/document-type",
                            "code": "ccda"
                        }
                    ]
                },
                "category": {
                    "coding":  [
                        {
                            "system": "http://ihis.sg/cs/ccda-data-group",
                            "code": "discharge-summary"
                        }
                    ]
                },
                "subject": {
                    "type": "Patient",
                    "identifier": {
                        "system": "http://ihis.sg/identifier/encrypted-nric",
                        "value": "U2FsdGVkX1-eXowTVO3diSIV_xq8kIME4BxcsYYrh-s="
                    }
                },
                "date": "2023-10-01T12:00:00Z",
                "author":  [
                    {
                        "type": "Organization",
                        "identifier": {
                            "system": "http://ihis.sg/identifier/institution-code",
                            "value": "ttsh"
                        }
                    }
                ],
                "content":  [
                    {
                        "attachment": {
                            "contentType": "application/jpeg",
                            "url": "/Binary/eimr-ttsh-U2FsdGVkX18KFMPcFnDTG2XO1pP0KO9GEZwFJlnU6bc=:d428e7db-2964-44be-855b-00c7475da6cb"
                        }
                    }
                ]
            },
            "request": {
                "method": "GET",
                "url": "DocumentReference"
            }
        },
        {
            "fullUrl": "urn:uuid:docref2",
            "resource": {
                "resourceType": "DocumentReference",
                "id": "2",
                "meta": {
                    "source": "http://ihis.sg/source-system/erx"
                },
                "identifier":  [
                    {
                        "system": "http://ihis.sg/identifier/ccda",
                        "value": "guid"
                    }
                ],
                "status": "current",
                "docStatus": "final",
                "type": {
                    "coding":  [
                        {
                            "system": "http://ihis.sg/cs/document-type",
                            "code": "ccda"
                        }
                    ]
                },
                "category": {
                    "coding":  [
                        {
                            "system": "http://ihis.sg/cs/ccda-data-group",
                            "code": "lab-report"
                        }
                    ]
                },
                "subject": {
                    "type": "Patient",
                    "identifier": {
                        "system": "http://ihis.sg/identifier/encrypted-nric",
                        "value": "U2FsdGVkX1-eXowTVO3diSIV_xq8kIME4BxcsYYrh-s="
                    }
                },
                "date": "2023-10-01T12:00:00Z",
                "author":  [
                    {
                        "type": "Organization",
                        "identifier": {
                            "system": "http://ihis.sg/identifier/institution-code",
                            "value": "ttsh"
                        }
                    }
                ],
                "content":  [
                    {
                        "attachment": {
                            "contentType": "application/json",
                            "url": "/Composition/eimr-ttsh-U2FsdGVkX18KFMPcFnDTG2XO1pP0KO9GEZwFJlnU6bc=:d428e7db-2964-44be-855b-00c7475da6cb"
                        }
                    }
                ]
            },
            "request": {
                "method": "GET",
                "url": "DocumentReference"
            }
        }
    ]
}
4xx, 5xx 
{
    "resourceType": "OperationOutcome",
    "id": "notfound",
    "issue":  [
        {
            "severity": "error",
            "code": "patient-nric-not-found",
            "details": {
                "coding":  [
                    {
                        "system": "http://fhir.synapxe.sg/api-operation-outcome",
                        "code": "E-10000"
                    }
                ],
                "text": "Patient NRIC is not found"
            }
        }
    ]
}

Business Level Errors

This section details the business level errors exposed by OperationOutcome resource for this operation. Refer to API Error Handling for framework level errors.

For illustration only

http status code code details.coding.code details.text
404 patient-nric-not-found E-10000 Patient NRIC is not found
404 source-system-not-found E-10001 Source system is not found
404 source-institution-not-found E-10002 Source Institution code is not found
404 document-category-not-found E-10003 Document Category is not found