From 5fc7d8b9313affdbea4a2f316b588469cf4f73fc Mon Sep 17 00:00:00 2001 From: Bas van den Heuvel Date: Fri, 5 Jun 2026 09:40:49 +0200 Subject: [PATCH 1/2] Enhance messaging documentation with asynchronous response details and update mapping exceptions for ServiceRequest --- source/messaging.html | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/source/messaging.html b/source/messaging.html index 3bed64dd48a..aeaae4786c6 100644 --- a/source/messaging.html +++ b/source/messaging.html @@ -396,7 +396,43 @@

Asynchronous Messaging using the RESTful API

It is possible to exchange messages using the RESTful end-point as a central point of exchange. This is not particularly efficient compared to other methods, but -is useful for low-volume asynchronous exchange. +is useful for low-volume asynchronous exchange (see Asynchronous Application Responses). +

+ +

Asynchronous Application Responses

+

+Messaging intrinsically supports asynchronous processing at the payload level, rather than at the protocol level. +In typical REST interactions, if a response is not ready right away, there is a need to use protocol-level +asynchronous processing. However, with messaging, responses can always be handled +as another message payload from initial recipient to initial requester. As a result, there is no need to +(and is rarely, if ever, appropriate to) use RESTful asynchronous processing in situations where an immediate +business response cannot be provided. +

+

+If the system responding to a message might not be able to fully process the event in the timeframe required by +the transport technology (e.g. before an HTTP timeout), there are two possibilities: +

+ +

+In either case, the eventual full response (if one is needed) is handled by transmitting a new message, +this time from initial recipient to initial requester. In some cases, there could be a series of back-and-forth messages. +

+[%impl-note%] +Previous releases used a combination of Bundle.id and MessageHeader.id in an attempt to +establish message identity. This posed problems when crossing boundaries between messaging and RESTful exchange. +This release uses Bundle.identifier exclusively to establish and maintain message identity. +[%end-note%] +

Message Delivery without Operations

+

+In a RESTful environment, rather than invoking a $process-message operation, it is possible to perform +a create of message Bundles on a server and for recipients to poll or subscribe to receive messages and delete them +once processed. Unlike request resources, messages always have an implicit "please process" for the recipient.

To send a message, a sender posts the message bundle to the From c921f468e1152c4cac9f4b25da117caefb5d5843 Mon Sep 17 00:00:00 2001 From: Bas van den Heuvel Date: Fri, 5 Jun 2026 09:50:01 +0200 Subject: [PATCH 2/2] FHIR-46564: Replace asynchronous REST messaging subsection content - Replace the subsection text with the resolution-driven asynchronous application response guidance - Add delayed-response guidance using MessageDefinition.allowedResponse and HTTP 200 with no body for $submit-message - Remove legacy step-by-step REST polling/search walkthrough text from the replaced subsection --- source/messaging.html | 35 ----------------------------------- 1 file changed, 35 deletions(-) diff --git a/source/messaging.html b/source/messaging.html index aeaae4786c6..4dc0fc9eb2b 100644 --- a/source/messaging.html +++ b/source/messaging.html @@ -434,41 +434,6 @@

Message Delivery without Operations

a create of message Bundles on a server and for recipients to poll or subscribe to receive messages and delete them once processed. Unlike request resources, messages always have an implicit "please process" for the recipient.

-

-To send a message, a sender posts the message bundle to the -/Bundle end-point, with a uri that identifies the receiver -at MessageHeader.destination.endpoint. -The RESTful server accepts the bundle, -stores it as a single resource, and indexes it on the contents of the included -MessageHeader. -

-

-To receive messages, a receiver searches for all messages -destined for itself, since its last check: -

-
- GET [base]/Bundle?message.destination-uri=[rcv]&_lastUpdated=gt2015-03-01T02:00:02+01:00
-
-

-The receiver works through the response, processing each message. -As each message is processed, the receiver creates a response -message, reversing the source and destination, and posts it back -to the server. -

-

-To check for responses, the original sender searches for -response messages destined for itself, since its last check: -

-
- GET [base]/Bundle?message.destination-uri=[snd]&message.response-id:missing=false
-      &_lastUpdated=gt2015-03-03T06:03:522+01:00
-
-

-This lightweight protocol needs ongoing administration to -ensure that multiple parties do not interfere with each other -by re-using the same system identifier (and against malicious -attack). -

MessageHeader and REST

The MessageHeader is important and necessary when interpreting the contents of a message - they cannot be understood without it. However once resources are removed from the message Bundle, and processed into some other context (e.g., PUT/POST to a RESTful API, or deconstructed into a database, or transferred into any other context), the content of the MessageHeader SHALL NOT be relevant for interpreting the contents of the resource. To be explicit, applications using a RESTful API are not required to look for past MessageHeader resources that relate to a resource in order to understand the resource correctly.