Proper use of the Bundle resource

Hello to the community. I’ve been digging into the FHIR spec with the intent of exposing the FHIR resources via a REST-based API. One question I had was on the proper use of Bundle resource, and whether it can be used when returning a resource that naturally has relationships to other resources, such as the Detected Issue resource, which in one of the examples, provides back references to a MedicationStatement resource and a MedicationOrder resource. You only get a reference, however.

On the surface, it doesn’t seem to make sense to have an inquiry like:
GET /detectedIssue/{id}
return a Bundle resource, rather than a DetectedIssue resource.

Is anyone using Bundle in this type of scenario, or is strictly being used in either message-based interactions or where you have a need for an attributed collection?

For the record, using Bundle for the scenario I describe does feel like it’s going against the spirit of the spec. As a result, however, it does mean that there are a number of resources that must have APIs out of the gate to get started.

Thanks!

If you do a GET [base]/DetectedIssue/{id}, then you MUST return a bare DetectedIssue instance. However, you can do this: GET [base]/DetectedIssue?_id={id}&_include={whatever} to bring back a resource and its related records (specifying an _include for each relationship you want to come back).

Thanks, I did see that an appropriate use of the Bundle resource was when doing a find-style request (GET without a unique identifier in the path and query parameters for matching/filtering). So, in the example you describe, the response object would be a Bundle resource. In this case, what’s the recommendation for specifying paths to dependent resources in references? E.g. If I have a MedicationStatement in my Bundle, and a DetectedIssue that refers to that, would the following be correct? (JSON)… I assume it’s up to the consumer to realize that the Patient referred to in the DetectedIssue resource has the same ID as specified in the Bundle (although the reference is expressed as a relative URL, so they’d need to be smart enough to parse out the id)…

{
	"resourceType": "Bundle",
	"id": "dynamicBundle-1234",
	"entry" [
	 	{
	 		"resource": {
	 			"resourceType": "MedicationStatement",
	 			"id": "0a92efb8-c709-4c00-8e8e-a4127992e3ff",
	 			...
	 		}
	 	},
	 	{
	 		"resource": {
	 			"resourceType": "Patient",
	 			"id": "123e4567-e89b-12d3-a456-426655440000",
	 			...
	 		}
	 	},
	 	{
	 		"resource": {
	 			"resourceType": "DetectedIssue",
	 			"id": "a397fefd-802b-49fc-8043-a8db9199025a",
	 			"patient:" {
	 				"reference": "/Patients/123e4567-e89b-12d3-a456-426655440000",
	 			},
	 			...,
	 			"implicated": [
	 				{
	 					"reference": "MedicationStatements/0a92efb8-c709-4c00-8e8e-a4127992e3ff"
	 				}
	 			],
	 			...
	 		}
	 	}
	]
}

References can be absolute or relative. If relative, the reference format it {ResourceName}/{id}(/_history/{version})? So “reference”: “Patient/123e4567…”

And that’s true regardless of whether the referenced resources are part of the bundle or not. (A relative reference means that the referenced resource is found on the same server as the referencing resource.)

Follow up to this question from a while ago…

Is it REQUIRED to use a Bundle resource when responding to a find-style inquiry, e.g. GET [base]/DetectedIssue?id={id}&include={whatever}, or is it acceptable to simply return a collection of resources (e.g. JSON array)?

If you are doing a search, you MUST return the responses using a Bundle resource if you want to be FHIR conformant.

Side note, the correct query in STU2 would be:
[base]/DetectedIssue?_id={id}&_include={whatever}

I.e. the standard search parameters all start with “_”.

Just posting this here in case anyone else is trying to find where the spec states the requirement for Bundle…
https://www.hl7.org/fhir/http.html

2.1.0.14: search

If the search fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx with an OperationOutcome. If the search succeeds, the return content is a Bundle with type = searchset containing the results of the search as a list of resources in a defined order.