This page is part of the FHIR Specification (v0.0.82: DSTU 1). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions

2.6 How to Use Resources

2.6.1 Service Orientated use of Resources

While the FHIR Resources are designed with a simple RESTful HTTP-based implementation in mind, it is not necessary to use this implementation framework. This specification also defines a straight messaging based implementation framework for FHIR resources and a document-based framework.

Alternatively, it is not necessary to use any of these approaches. Resources can be exchanged or persisted using any technical means that is appropriate to the context at hand. A common use of FHIR resources or bundles is as parameters of service interfaces. FHIR itself does not define any particular service interface. Instead, other standards and implementations define their own service interfaces and architecture that use FHIR resources and optionally build extra features on top of the base repository-mediated exchange that the FHIR RESTful specification provides. As long as the resources that are used are conformant with this specification and the rules for authoring and reading applications are followed, then the implementation can claim conformance to "FHIR Resources". Such implementations will need to resolve several issues:

• Resource identity (the "id" metadata property) must be maintained. Resources all have an identity, which is how other resources refer to them, and these references need to be able to be resolved. However resources are exchanged, their identity - which is not included inside the resource - needs to be included with the resource
• Resource references need to be resolvable. There are a variety of solutions to this, from ensuring that all the relevant resources are bundled together or that all relevant resources are passed as parameters in a service call, through to having a resource repository in the background that provides access to all referenced resources.
• The Resource metadata items "Version Id" and "Last Modified Date" are provided for use in resolving resource versioning and concurrency issues, both from a technical and human perspective. Most contexts of use will require at least one if not both of these attributes for some uses, and the implementation framework will need to resolve how and when they are exchanged.
• The conformance statement allows authoring and reading applications to describe their rules concerning the use and contents of a resource. The implementation will need to describe how this conformance statement or some other equivalent fits into the exchange/persistence context.
• How transactional information such as data enterer, author(s), responsible party, consent and approvals is treated

The resolution to these issues should be documented and published with the service specification.

2.6.2 Managing Resource Identity

Each resource has a known identity. The identity is not stored inside the resource, but must be tracked by systems handling resources. For RESTful systems, the resource identity is the same as the URL by which it is found. When a resource is packaged in a bundle, the id is included along with the resource. Real-world use of FHIR resources creates the need to manage resource identification.

Resources are used in a variety of circumstances. Generally, these can be categorized into 3 different scenarios:

1. Closed Trading System: the resources are only ever exchanged between fixed systems in a tightly controlled community, such as a hospital. There is only one master server for each resource type, and resources are managed by that server. In this context, the logical id of a resource is sufficient to fully identify the resource
2. World-wide RESTful system: there are many peer servers, each managing a set of resources of different types. In order to identify resources, a full URL reference to the origin server is required
3. Partially closed, inter-linked systems: a mixture of both - trading communities that are tightly managed, but have managed interactions with other closed trading systems, or with the world-wide RESTful system, or both. In fact, this combination appears to be the most likely scenario for current real-world healthcare business solutions

These combinations show why either relative (logical) or absolute references are allowed, and why a logical id is always required, in order to enable seamless exchange amongst partially closed trading systems.

2.6.3 Copying Resources and re-identification

When resources are exchanged between systems, they may need to be re-identified (i.e. assigned a new resource). When a resource is re-identified, nothing in the resource changes, but any references that point to the resource need to be updated. Whether re-identification is required or not depends on the context, as does how resource references are updated.

The normal case is that a client/receiving system accepts the server/sender's identification of a resource at the face value, whether it is a relative or absolute reference. When the client/receiver wants to follow resource references, they are done using the server id (typically either by http calls or locating them in a bundle). In such cases, there is no need for re-identification.

Another scenario is for a client to retrieve a resource from a server, and make its own local persistent copy. If the local resource has a life-cycle of its own (i.e. it is not just a cached resource), then it needs to have its own identity; i.e. the resource must be re-identified. The simplest case is that the client only is keeping local copies of resources from a single server. In these cases, the client can simply replace the root URL and keep the logical id of the resource the same. In fact, if the server is using relative references, then this change doesn't involve any actual changes to the resources, only a re-interpretation of the references.

In some cases, however, the client may deal with multiple servers. In this case, the logical id of the resource is not guaranteed to be unique (unless all resources have a UUID for the logical id, which is allowed but not required). When the client cannot be sure that the resource identities are unique, it will have to re-identify the resources. In practice this means that the client needs to keep an identity translation table, and update references to the resources it has copied locally when other resources are received.

The case of a gateway system that migrates resources from one ecosystem to another is very similar. In some limited cases, it can leave the logical id of the resources unchanged as resources are copied from one closed system to another. However in more complicated cases, it will have to modify the resource references as resources pass across the gateway.

2.6 Workflow with resources

There are many ways to implement any particular workflow and there are many ways to use resources to build working systems:

• A RESTful paradigm where resources are exchanged separately using http transactions directly as defined in this specification. Implementations can use both push and pull or a mix of the two
• The resources can be exchanged in messages or some other SOA implementation where the resources form the contents/parameters that are exchanged
• The resources can be "bundled" into documents that are self-contained and complete collections of linked resources and then these documents can be exchanged and/or persisted
• The resources can be embedded in HTML pages or other web content such as content feeds