FHIR:Vissue-MM-2759 Search result examples

Example: read support for all resources

Scenario	The server offers read support for all resources that it has, meaning that each resource has a stable Resource.id and is accessible through a stable RESTful URL.
Request	GET [base]/Observation
Response	Searchset Bundle containing 1 Observation resource. References from the Observation resource are to other resources on the server.
XML contents - response <Bundle xmlns="http://hl7.org/fhir" > <!-- Bundle.id is not different than any other Resource.id --> <id value="example-id1"/> <!-- Bundle.type should be set to 'searchset' --> <type value="searchset"/> <!-- Bundle.total is set to the number of matches for the request --> <total value="1"/> <!-- The "self link" shows the search request as how it was understood by the server --> <link> <relation value="self"/> <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/> </link> <entry> <!-- The Observation resource is accessible through a RESTful URL, which is used for the fullUrl --> <fullUrl value="https://example-server.nl/fhir/Observation/observation-123"/> <resource> <Observation> <!-- The Resource.id MUST be populated when it is accessible using a RESTful URL. --> <id value="observation-123" /> ... <subject> <!-- The Patient resource resides on the same server and can be referenced using a relative URL. An absolute URL could be used in this case as well. --> <reference value="Patient/patient-123" /> </subject> ... </Observation> </resource> <search> <!-- Resources that match the search request have mode set to 'match' --> <mode value="match"/> </search> </entry> </Bundle>

Example 2: server doesn't support read operations

Scenario	The server supports doesn't support the read operation, for example because it's a FHIR facade that is unable to link a stable id to a certain entry in the underlying database. For this reason, it only supports searching for data.
Request	GET [base]/Observation
Response	Searchset Bundle containing 1 Observation resource and all referenced resources. References from the Observation resource are to other resources within the Bundle. All resources in the Bundle are identified using a temporary fullUrl.
XML contents - response <Bundle xmlns="http://hl7.org/fhir"> <!-- Bundle.id is not different than any other Resource.id --> <id value="example-id2"/> <!-- Bundle.type should be set to 'searchset' --> <type value="searchset"/> <!-- Bundle.total is still set to the number of _matches_, even though more resources are included in the Bundle. --> <total value="1"/> <!-- The "self link" reflects the search as it was understood by the server --> <link> <relation value="self"/> <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/> </link> <!-- The server is unable to offer a stable RESTful URL to the Patient resource, but it needs to satisfy the requirement that all resources are resolvable. Therefore, it includes the referenced Patient resource in the searchset Bundle. --> <entry> <!-- Since the server is unable to produce a RESTful URL for reading the resource, so it uses an ephemeral fullUrl so that other resources in the Bundle can refer to it. --> <fullUrl value="urn:uuid:69aefd96-b37d-4323-866b-762536c03375"> <resource> <Patient> .... </Patient> </resource> <search> <!-- When resources are additionally included in the searchset Bundle while there's no direct match, .search.mode should be set to 'include'. --> <mode value="include" /> </search> </entry> <entry> <!-- Note that the fullUrl MUST be populated, even if this resource is not referred by any other resource within the Bundle. (?) Since the server is unable to produce a RESTful URL for reading the Observation resource, it creates an ephemeral fullUrl for this resource as well. --> <fullUrl value="urn:uuid:799c5790-f2aa-4045-8c19-a0d54773a059"/> <resource> <Observation> ... <subject> <!-- The server doesn't support read for the Patient resource, so it's included in the Bundle using an ephemeral fullUrl. --> <reference value="urn:uuid:69aefd96-b37d-4323-866b-762536c03375" /> </subject> ... </Observation> </resource> <search> <mode value="match"/> <!-- Resources that match the search request have mode set to 'match' --> </search> </entry> </Bundle>

Example 3: read support for some resources (hypothetical)

<Bundle xmlns="http://hl7.org/fhir" >
    <!-- Bundle.id is not different than any other Resource.id -->
    <id value="example-id3"/>
    
    <!-- Bundle.type should be set to 'searchset' -->
    <type value="searchset"/>

    <!-- Bundle.total is still set to the number of _matches_, even though more resources are included -->
    <total value="1"/>
    
    <!-- The "self link" shows the search request as how it was understood by the server -->
    <link>
        <relation value="self"/>
        <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/>
    </link>
    
    <entry>
        <!-- 
          Since the server is unable to produce a RESTful URL for reading the Observation resource, it creates an ephemeral fullUrl
          for this resource.
          Note that the fullUrl MUST be populated, even if this resource is not referred by any other resource within the Bundle. (?)
        -->
        <fullUrl value="urn:uuid:e07ffa10-c043-4dd6-aa52-6ac273c82da9"/>
        <resource>
            <Observation>
                ...
                <subject>
                    <!--
                      The server supports read for the Patient resource, so an absolute URL can be used.
                      Note that a relative URL is invalid in this case, because it is deemed relative to the fullUrl of the Observation resource.
                      Since this fullUrl is not a RESTful URL, a relative URL cannot be resolved to an actual URL. -->
                    -->
                    <reference value="http://example-server.nl/Patient/patient-123" /> 
                </subject>
                ...
            </Observation>
        </resource>
        ...
    </entry>
</Bundle>

Scenario	The server is able to produce a stable RESTful URL for the Patient resource, but not for the Observation resource. This is a highly hypothetical situation to demonstrate the boundaries of the reference resolving mechanism in FHIR Bundles.
Request	GET [base]/Observation
Response	Searchset Bundle containing 1 Observation resource. References from the Observation resource are to other resources on the server, using an absolute URL. The Observation resource is identified using a temporary fullUrl.	XML contents - response

Invalid example: using contained resources

Scenario	The server supports doesn't support the read operation, for example because it's a FHIR facade that is unable to link a stable id to a certain entry in the underlying database. For this reason, it only supports searching for data.
Request	GET [base]/Observation
Response	Searchset Bundle containing 1 Observation resource. The referenced Patient resource is contained within the Observation resource. This approach is invalid! Resources should only be contained if they cannot have an independent existence outside of the resource containing it. This is not the case in the current situation.
XML contents - response <Bundle xmlns="http://hl7.org/fhir" > ... <entry> <fullUrl value="urn:uuid:2290607c-79e8-47ed-a23e-b8c3d5f224b2"/> <resource> <Observation> ... <contained> <Patient> <id value="patient1"/> ... </Patient> </contained> ... <subject> <!-- Wrong approach: the server is unable to offer a stable RESTful URL to the Patient resource, but it needs to satisfy the requirement that all resources are resolvable. Therefore, it sends the Patient resource as a contained resource within the Observation resource. Resources should only be contained if they cannot have an independent existence outside of the resource containing it. This is not the case in the current situation, so this approach is invalid! --> <reference value="#patient1" /> </subject> ... </Observation> </resource> ... </entry> </Bundle>