Fhir 46564

source/messaging.html

@@ -396,42 +396,43 @@ <h3>Asynchronous Messaging using the RESTful API</h3>
 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 <a href="#async">Asynchronous Application Responses</a>).
 </p>
+<a name="async"></a>
+<h4>Asynchronous Application Responses</h4>
 <p>
-To send a message, a sender posts the message bundle to the
-/Bundle end-point, with a uri that identifies the receiver
-at <a href="messageheader-definitions.html#MessageHeader.destination.endpoint">MessageHeader.destination.endpoint</a>.
-The RESTful server accepts the bundle,
-stores it as a single resource, and indexes it on the contents of the included
-<a href="messageheader.html">MessageHeader</a>.
+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
+<a href="async.html">asynchronous processing</a>. 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.
 </p>
 <p>
-To receive messages, a receiver searches for all messages
-destined for itself, since its last check:
-</p>
-<pre>
- GET [base]/Bundle?message.destination-uri=[rcv]&amp;_lastUpdated=gt2015-03-01T02:00:02+01:00
-</pre>
-<p>
-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.
+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:
 </p>
+<ul>
+  <li>In some cases the <a href="messagedefinition.html">MessageDefinition</a> for the original message might have an
+    <code>allowedResponse</code> that indicates the response is in progress, pended, or a similar business concept.
+    In that case, such a response can be included as the response body of the initial 200 OK.</li>
+  <li>In other cases, there will not be an appropriate message-level response available. In that situation,
+    the response to the initial <code>$submit-message</code> will simply be an HTTP 200 with no body.</li>
+</ul>
 <p>
-To check for responses, the original sender searches for
-response messages destined for itself, since its last check:
+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.
 </p>
-<pre>
- GET [base]/Bundle?message.destination-uri=[snd]&amp;message.response-id:missing=false
-      &amp;_lastUpdated=gt2015-03-03T06:03:522+01:00
-</pre>
+[%impl-note%]
+Previous releases used a combination of <code>Bundle.id</code> and <code>MessageHeader.id</code> in an attempt to
+establish message identity. This posed problems when crossing boundaries between messaging and RESTful exchange.
+This release uses <code>Bundle.identifier</code> exclusively to establish and maintain message identity.
+[%end-note%]
+<h4>Message Delivery without Operations</h4>
 <p>
-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).
+In a RESTful environment, rather than invoking a <code>$process-message</code> 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.
 </p>
 <h4>MessageHeader and REST</h4>
 <p>