Readers Guide and use of RESTful FHIR API

The implementation guide uses the mechanisms described in the Profiling chapter of the HL7 FHIR specification to describe the interface from the Person information Service:

https://www.hl7.org/fhir/profiling.html#5.1.0

The implementation guide will have three main parts.

Top level description of the use-cases supported (Use-case)
Top level description of the server requirements for the Person Information Service (Service Interface)
Detailed description of the HL7 FHIR based information model (Person Information)

In addition to the main parts there is also a chapter describing all extensions that are part of the package and a Readers guide (this chapter).

Common conformance definitions

HL7 FHIR Conformance language

This specification uses the conformance verbs SHALL, SHOULD, and MAY as defined in RFC 2119. Unlike RFC 2119, however, this specification allows that different applications might not be able to interoperate because of how they use optional features. In particular:

SHALL: an absolute requirement for all implementations

SHALL NOT: an absolute prohibition against inclusion for all implementations

SHOULD/SHOULD NOT: A best practice or recommendation to be considered by implementers within the context of their particular implementation; there may be valid reasons to ignore an item, but the full implications must be understood and carefully weighed before choosing a different course

MAY: This is truly optional language for an implementation; can be included or omitted as the implementer decides with no implications

Must support

Any FHIR element can have a flag set called must support. The must support flag can have three flavors, true, false and the flag can be missing (not set). must support elements is marked by a red S in the documentation on each resource. Like the propertyInformation, cadastralAddress and separatelyOccupiedUnit in the

Command 'link' could not render: Object reference not set to an instance of an object.

below:

Command 'tree' could not render: Project was not found for Grunndata-r4/AddressCadastral.

Must support definitions

In the context of Master Person Index, Must Support on any data element SHALL be interpreted as follows:

Must support = true

Usually this means that the Responders should include the data in the query result if the data is present for the given resource instance.

Responders SHALL be capable of including the data element as part of the query results as specified by the Server Capability Statement. In situations where information on a particular data element is not present and the reason for absence is unknown, Responders SHALL NOT include the data elements in the resource instance returned as part of the query results.

Requestors SHALL be capable of processing resource instances containing the data elements without generating an error or causing the application to fail. Requestors SHOULD be capable of displaying the data elements for human use. Requestors SHOULD be able to store the information for other purposes.

must support = false

Usually this means that Responders has no data to populate the element and Requestors is not expected to display the data elements for human use.

Responders SHALL NOT be capable of including the data element as part of the query results as specified by the Server Capability Statement.

Requestors MAY be capable of displaying the data elements for human use. Requestors SHOULD be able to store the information for other purposes. Requestors SHALL be capable of processing resource instances containing the data elements without generating an error or causing the application to fail.

must support not set

If the must support flag is not set no requirements exist as to wether the data is expected to be included in the search result. In most cases this means that the information is not awailable to the Responders, but the information could be included in a later version.

Responders MAY be capable of including the data element as part of the query results as specified by the Server Capability Statement.

Must support rendering in the Implementation guide

Unfortunately the Implementation guide rendering of the must-support flag is not perfect on the SIMPLIFIER platform. Only the instances where the must support = true is rendered in the resource-profile overview (look for the red "S" in the profile rendering). The flag is not even included in the detailed rendering. This results in a situation where the rendering is not able to show the difference between must support = false and not-set. This distinction is only visible in the StructureDefinition XML.

Read interaction

GET [base]/[Resource-type]/[id] {parameters}

GET is the HTTP verb used for fetching a resource

Content surrounded by [] is mandatory, and will be replaced by the string literal identified.
base: The Service Root URL (e.g. “https://fhir-open-api-dstu2.smarthealthit.org”)
Resource-type: The name of a resource type (e.g. “Person”)
id: The Logical Id of a resource(e.g. “24342”)
Content surrounded by is optional
parameters: URL parameters as defined for the particular interaction (e.g.”?_format=xml”}

Example
`GET http://hapi.fhir.org/baseR4/Person/53098`

For more information see the FHIR RESTful API

Search interaction

For searching a resource, interactions on profile pages are defined with the following syntax:

GET [base]/[Resource-type]?name=value&...

For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name “code” for search on the LOINC code. For more information see the FHIR RESTful Search API

To search for RelatedPersons og Provenance resources connected to a Person you need to include the Person identifier in the search parameters of the related resource.

GET [base]/RelatedPerson?patient=[id]
GET [base]/RelatedPerson?patient:identifier=[system]|[code]

Example
`GET [base]/RelatedPerson?patient=53098`

Special note on searching on person identifier

The person identifiers (DNR and FNR in particular) is considered sensitive data that should not end up in any access logs of the server system. Usually HTTP parameters from the HTTP request will end up in the logs and could be read by personnell accessing these logs. The preferred method to avoid this happening is to use a POST transaction for searching on these parameters and put the search parameters in the body of the HTTP message like this:

Example
`POST /baseR4/Person/_search HTTP/1.1` `Host: hapi.fhir.org` `Content-Type: application/x-www-form-urlencoded` `Cache-Control: no-cache` `Postman-Token: b43d58f5-f006-fe4a-4fc3-e8c60e1af589` `identifier=urn%3Aoid%3A2.16.578.1.12.4.1.4.1%7C04021950128`

The CapabilityStatement specifies what search parameters that requires a POST transaction for searching.

Dataminimization by default

The service expects the clients to specify what information elements they need (based on "tjenstlig behov") using the _elements operation. When the _elements operation is missing from the read/search statement, no information is returned to the client.

_total parameter

The return Bundle has an element total which is the number of resources that match the search parameters. The _total parameter makes it possible to specify what information the client needs for the total element in the return Bundle.

The Service has a default value of none set for the _total parameter. The default value reduce the server load for large search-sets. The default behaviour can be changed by setting the _total parameter in the search request, please consider not changing the _total parameter to accurate unless your client really needs this information.

Guidance On Limiting The Number Of Search Results

In order to manage the number of search results returned, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links. See the managing returned resources in the FHIR specification for more information.

History of a resource

Every Person resource returned by the server contains both currently active information and all information that was active at some earlier point in time, (e.g. historic information). The consumer of the information must read the fregMetadata.currentInfo element to tell the current and historic information apart.

Thus the historic information of resources from the Master Person Index deviates from how this is usually implemented on FHIR servers using the _history operation.

HTTP Status Codes

HTTP status codes are handled as described in the FHIR RESTful API specification.