Using Bundles with Opala's APIs
A bundle is an infrastructure container for a group of gathered resources with containing context that is treated as a single instance. A bundle does not have narrative and is used to group collections of resources for transmission, persistence, or processing.
There are two ways to collect resources together for transport and persistence purposes — contained resources and bundles. There is an important difference between the two:
- Contained resources are "in" the container resource; that is, they can only ever be interpreted and/or changed in the context of the container.
- A bundle is a collection of resources that can have an independent existence. For example, the resources in a bundle might also be accessed directly using the RESTful API.
A FHIR bundle contains an array of entries, each of which represents an operation, such as create, update, or delete, on a resource, such as an Observation or a Patient. Opala's bundles paginate with 50 resources per page. To see the next 50, use the next link in the bundle's header.
Note: Opala does not currently support Live Bundles.
Using Bundles
There are several reasons to bundle resources:
- RESTful Search. A set of returned resources that meet some criteria as part of a server operation.
- History. A set of versions of resources returned as part of the history operation on a server.
- Messaging. A set of resources sent as part of a message exchange.
- Documents. A self-contained set of grouped resources that act as an exchangeable and persistable collection with clinical integrity (e.g., a clinical document).
- Transactions. A set of resources that you can create/update/delete on a server as a single operation (including as a single, atomic transaction).
- Storage. A set of resources that can be stored as a collection using a bundle.
As a bundle is a group of transactions, each element within a bundle is validated as a transaction. The bundle is the container which wraps around the grouped resources.
However, there are also three administrative and infrastructure resources that support grouping content. These resources do not contain other resources directly; instead, they use [Reference] to point to the grouped resources.
- The List
resource. A flat, possibly ordered collection of records that provides features for managing the collection. The list resource references other resources. While a particular List instance may represent a snapshot, from a business process perspective a List is dynamic: items are added and removed over time.
List resources are used in many places, including allergies, medications, alerts, family history, medical history, etc.
The List resource is only needed if there is a necessity to filter the set of resources by a mechanism that cannot be accomplished using a simple query. Querying a list of resources such as AllergyIntolerance, Condition, or Medication-related resources is different than querying the resource-specific endpoint. For example:
- A List of AllergyIntolerance resources represents a curated point-in-time snapshot of the patient's allergies and intolerances. Querying this List resource will return that point-in-time snapshot.
- However, querying the AllergyIntolerance endpoint typically produces a larger set of records since it is both non-curated (potentially containing duplicate or out-of-date records) and current (generated based on information as of now, rather than being generated based on the last time a human manually revised the List resource instance).
- The Group resource. A collection of specific people, animals, devices, etc., defined by enumerating them, or by describing qualities that the group members have. The group resource refers to other resources, either explicityly or implicitly. Groups are intended to be acted upon or observed as a whole (e.g., performing therapy on a group, calculating risk for a group). This resource is commonly used for public health, clinical trials, and similar purposes, for example, describing an at-risk population or defining a test subject pool.
- The Composition resource. A set of healthcare-related information that is assembled together into a single logical document which provides a single coherent statement of meaning, establishes its own context, and that has clinical attestation with regard to who is making the statement. The composition resource provides the basic structure of a FHIR document . The full content of the document is expressed using a Bundle. Compositions will often reference Lists as the focus of particular sections.
These three resources represent meaningful groupings of the resources they refer to (e.g. a discharge medication List, a Group of participants for a clinical trial, a set of resources that form a signed document), while a Bundle is merely is a container for resources used for transfer and storage. This list is not exhaustive; other resources also provde grouping functionality.
Additional Resources
