https://jira.hl7.org/browse/FHIR-42823 - Fixed some actors in exchang…

images/source/rest.plantuml

@@ -2,6 +2,6 @@
 hide footbox
 participant "Data Consumer" as Consumer
 participant "Data Source" as Source
-Consumer -> Source: 1a. POST/PUT/PATCH resource/Bundle
-Consumer <-- Source: 1b. HTTP 200/201 (possibly with result resource/Bundle)
+Source -> Consumer: 1a. POST/PUT/PATCH resource/Bundle
+Source <-- Consumer: 1b. HTTP 200/201 (possibly with result resource/Bundle)
 @enduml

source/exchanging-rest.html

@@ -42,26 +42,26 @@ <h3>push</h3>
   <a name="async"> </a>
   <h3>async</h3>
   <p>
-    This pattern is used for a subset of the <a href="#push">push</a> scenarios.  The request goes from the <i>data source</i> to the <i>data consumer</i>, but the requested action does not complete immediately.  Instead, the <i>data consumer</i> delivers the response later.  The <i>data source</i> polls to see what the results are.  This will be most commonly used with the <a href="bundle.html">Bundle</a>-based actions which are processing multiple actions at once and may take longer than the HTTP time-out window allows.  (Note: In theory, it would be possible to use async for <a href="#pull">pull</a> transactions like <a href="#read">read</a> or <a href="#vread">vread</a>.  However no known use case exists for these simple operations to happen asynchronously.
+    This pattern is used for a subset of the <a href="#push">push</a> scenarios.  The request goes from the <i>data consumer</i> to the <i>data source</i>, but the requested action does not complete immediately.  Instead, the <i>data source</i> delivers the response later.  The <i>data consumer</i> polls to see what the results are.  This will be most commonly used with the <a href="bundle.html">Bundle</a>-based actions which are processing multiple actions at once and may take longer than the HTTP time-out window allows.  (Note: In theory, it would be possible to use async for <a href="#pull">pull</a> transactions like <a href="#read">read</a> or <a href="#vread">vread</a>.  However no known use case exists for these simple operations to happen asynchronously.
   </p>
   <p>
     [%file rest-async.svg %]
   </p>
   <a name="async-1"> </a>
   <p>
-    <b>Step 1:</b> The invocation of the RESTful action asynchronously is identical to synchronous invocation, with the exception that the <code>Prefer</code> header is set to "respond-async".  (Note that the server is not obligated to respect the client's stated preference - it could still respond synchronously.)  The response includes a location-header that identifies where to monitor for the progress of the asynchronous request.
+    <b>Step 1:</b> The invocation of the RESTful action asynchronously is identical to synchronous invocation, with the exception that the <code>Prefer</code> header is set to "respond-async".  (Note that the source is not obligated to respect the consumer's stated preference - it could still respond synchronously.)  The response includes a location-header that identifies where to monitor for the progress of the asynchronous request.
   </p>
   <a name="async-2"> </a>
   <p>
-    <b>Step 2:</b> The <i>data source</i> <a href="exchanging-polling.html">polls</a> the location specified in step 1 to see if the operation is complete.  So long as it is not, it gets back a 202 Accepted HTTP response, possibly with a message indicating the degree of progress.  (Note: At any point, the <i>data source</i> could also <a href="async.html#3.1.6.3">cancel</a> the action, though cancellation of a state-changing action is not guaranteed).
+    <b>Step 2:</b> The <i>data consumer</i> <a href="exchanging-polling.html">polls</a> the location specified in step 1 to see if the operation is complete.  So long as it is not, it gets back a 202 Accepted HTTP response, possibly with a message indicating the degree of progress.  (Note: At any point, the <i>data consumer</i> could also <a href="async.html#3.1.6.3">cancel</a> the action, though cancellation of a state-changing action is not guaranteed).
   </p>
   <a name="async-3"> </a>
   <p>
-    <b>Step 3:</b> Once the action is complete, the response to the <i>data source</i>'s polling request changes to a 200 and conveys other information, including URLs to the location of the file (or files) that contain the results of the action.
+    <b>Step 3:</b> Once the action is complete, the response to the <i>data consumer</i>'s polling request changes to a 200 and conveys other information, including URLs to the location of the file (or files) that contain the results of the action.
   </p>
   <a name="async-4"> </a>
   <p>
-    <b>Step 4:</b> The <i>data source</i> retrieves the identified file or files from the <i>data consumer</i>, giving it confirmation of whether the requested action was successful.
+    <b>Step 4:</b> The <i>data consumer</i> retrieves the identified file or files from the <i>data source</i>, giving it confirmation of whether the requested action was successful.
   </p>
 
   <a name="actions"> </a>
@@ -85,15 +85,15 @@ <h4>Version-specific read (vread)</h4>
   <a name="create"> </a>
   <h4>RESTful create</h4>
   <p>
-    A <a href="http.html#create">create</a> follows the <a href="#push">push</a> pattern and uses the POST HTTP command to the <code>[base]/[resourceType]</code> endpoint to transmit a single resource from the <i>data source</i>, causing it to be stored on the <i>data consumer</i>.   If successful, the requested record will be persisted at the RESTful endpoint with a reliable id, potentially allowing it to be queried or referenced in subsequent exchanges.  The creation can be made conditional on the absence of specified data using the <a href="http.html#ccreate">If-none-exist</a> header.  The response might include a copy of what was actually stored (which could be different than what was transmitted), an <a href="operationoutcome.html">OperationOutcome</a> with any warning or information messages, or just the metadata indicating id and the version created.  While <a href="#async">asynchronous</a> use is theoretically possible, it would be uncommon for a create to take so long that synchronous operation was not possible.
+    A <a href="http.html#create">create</a> follows the <a href="#push">push</a> pattern and uses the POST HTTP command to the <code>[base]/[resourceType]</code> endpoint to transmit a single resource from the <i>data source</i>, causing it to be stored on the <i>data consumer</i>.   If successful, the requested record will be persisted at the RESTful endpoint of the <i>data consumer</i> with a reliable id, potentially allowing it to be queried or referenced in subsequent exchanges.  The creation can be made conditional on the absence of specified data using the <a href="http.html#ccreate">If-none-exist</a> header.  The response might include a copy of what was actually stored (which could be different than what was transmitted), an <a href="operationoutcome.html">OperationOutcome</a> with any warning or information messages, or just the metadata indicating id and the version created.  While <a href="#async">asynchronous</a> use is theoretically possible, it would be uncommon for a create to take so long that synchronous operation was not possible.
   </p>
 
   <a name="update"> </a>
   <h4>RESTful update</h4>
   <p>
-    A <a href="http.html#update">update</a> follows the <a href="#push">push</a> pattern and uses the PUT HTTP command to the <code>[base]/[resourceType]/[id]</code> endpoint to transmit a single resource from the <i>data source</i>, causing it to be stored on the <i>data consumer</i> with the specified resource id.  This is typically done to replace an existing version of the resource, but it can <a href="http.html#upsert">also be used</a> to create a brand new record if there was no prior resource at that location and the <i>data consumer</i> permits.  Some servers might also support <a href="http.html#cupdate">conditional update</a> using the <code>[base]/[resourceType]?[search parameters]</code> URL to create or update a resource where the id is unknown.
+    A <a href="http.html#update">update</a> follows the <a href="#push">push</a> pattern and uses the PUT HTTP command to the <code>[base]/[resourceType]/[id]</code>  endpoint to transmit a single resource from the <i>data source</i>, causing it to be stored on the <i>data consumer</i> with the specified resource id.  This is typically done to replace an existing version of the resource, but it can <a href="http.html#upsert">also be used</a> to create a brand new record if there was no prior resource at that location and the <i>data consumer</i> permits.  Some servers might also support <a href="http.html#cupdate">conditional update</a> using the <code>[base]/[resourceType]?[search parameters]</code> URL to create or update a resource where the id is unknown.
    </p>
-   <p>If successful, the requested record will be persisted at the RESTful endpoint with the specified id, potentially available to be queried or referenced in subsequent exchanges.  The response might include a copy of what was actually stored (which could be different than what was transmitted), an <a href="operationoutcome.html">OperationOutcome</a> with any warning or information messages, or just the metadata indicating id and the version created by the update. The update can be made conditional on the specified id being unchanged since last accessed, using the <a href="http.html#concurrency">If-match</a> header.  While <a href="#async">asynchronous</a> use is theoretically possible, it would be uncommon for an update to take so long that synchronous operation was not possible.
+   <p>If successful, the requested record will be persisted at the RESTful endpoint of the <i>data consumer</i> with the specified id, potentially available to be queried or referenced in subsequent exchanges.  The response might include a copy of what was actually stored (which could be different than what was transmitted), an <a href="operationoutcome.html">OperationOutcome</a> with any warning or information messages, or just the metadata indicating id and the version created by the update. The update can be made conditional on the specified id being unchanged since last accessed, using the <a href="http.html#concurrency">If-match</a> header.  While <a href="#async">asynchronous</a> use is theoretically possible, it would be uncommon for an update to take so long that synchronous operation was not possible.
   </p>
   <p>
     The workflow for update may be a bit more complex with a <a href="exchanging-search.html">search</a> happening prior to the update, particularly if conditional updates aren't supported.
@@ -114,7 +114,7 @@ <h4>Executing batches</h4>
   <a name="batch-search"> </a>
   <h4>Executing batch searches</h4>
   <p>
-    A 'search' batch is the same as any other type of <a href="#batch">batch</a>.  It is just that in a search batch, all the requested actions are different types of <a href="exchanging-search.html">search</a>.  Each entry in the batch-response will itself be a search-set Bundle.  It is possible to do paging on the search-set responses within the Bundle, but paging is on a per search-set basis, not on a Bundle basis.  (It is however possible to submit a new batch where each of the entries are a request for the 'next' set of results from some or all the previous queries.)
+    A 'search' batch is the same as any other type of <a href="#batch">batch</a>.  It is just that in a search batch, all the requested actions are different types of <a href="exchanging-search.html">search</a>.  The roles are also reversed, in that the batch is initiated by the <i>data consumer</i> on the server of the <i>data source</i>.  Each entry in the batch-response will itself be a search-set Bundle.  It is possible to do paging on the search-set responses within the Bundle, but paging is on a per search-set basis, not on a Bundle basis.  (It is however possible to submit a new batch where each of the entries are a request for the 'next' set of results from some or all the previous queries.)
   </p>
   <p>
     There is nothing to stop someone from submitting a transaction of searches, but there is little point because, by definition, a search cannot be interdependent on other resources and there is nothing to roll back in the event of a failure.  Thus, using transaction incurs needless cost.

source/rest.svg.html

@@ -1 +1 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="129px" preserveAspectRatio="none" style="width:471px;height:129px;background:#FFFFFF;" version="1.1" viewBox="0 0 471 129" width="471px" zoomAndPan="magnify"><defs><filter height="300%" id="f13m88oo4ztzcw" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="63" x2="63" y1="41.6094" y2="122.3125"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="412" x2="412" y1="41.6094" y2="122.3125"/><rect fill="#FEFECE" filter="url(#f13m88oo4ztzcw)" height="31.6094" style="stroke:#A80036;stroke-width:1.5;" width="113" x="5" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="99" x="12" y="26.5332">Data Consumer</text><rect fill="#FEFECE" filter="url(#f13m88oo4ztzcw)" height="31.6094" style="stroke:#A80036;stroke-width:1.5;" width="93" x="364" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="79" x="371" y="26.5332">Data Source</text><polygon fill="#A80036" points="400.5,69.9609,410.5,73.9609,400.5,77.9609,404.5,73.9609" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="63.5" x2="406.5" y1="73.9609" y2="73.9609"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="231" x="70.5" y="69.1045">1a. POST/PUT/PATCH resource/Bundle</text><polygon fill="#A80036" points="74.5,100.3125,64.5,104.3125,74.5,108.3125,70.5,104.3125" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="68.5" x2="411.5" y1="104.3125" y2="104.3125"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="325" x="80.5" y="99.4561">1b. HTTP 200/201 (possibly with result resource/Bundle)</text></g></svg>
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="125px" preserveAspectRatio="none" style="width:507px;height:125px;background:#FFFFFF;" version="1.1" viewBox="0 0 507 125" width="507px" zoomAndPan="magnify"><defs><filter height="300%" id="f1xerbiatxb5np" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="68" x2="68" y1="40.2969" y2="118.5625"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="445.5" x2="445.5" y1="40.2969" y2="118.5625"/><rect fill="#FEFECE" filter="url(#f1xerbiatxb5np)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="122" x="5" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="108" x="12" y="24.9951">Data Consumer</text><rect fill="#FEFECE" filter="url(#f1xerbiatxb5np)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="99" x="394.5" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="85" x="401.5" y="24.9951">Data Source</text><polygon fill="#A80036" points="79,67.4297,69,71.4297,79,75.4297,75,71.4297" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="73" x2="445" y1="71.4297" y2="71.4297"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="242" x="85" y="66.3638">1a. POST/PUT/PATCH resource/Bundle</text><polygon fill="#A80036" points="434,96.5625,444,100.5625,434,104.5625,438,100.5625" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="68" x2="440" y1="100.5625" y2="100.5625"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="354" x="75" y="95.4966">1b. HTTP 200/201 (possibly with result resource/Bundle)</text><!--SRC=[ROn12i8m44NtESNGbIxQj5sA25eNtLbeF43IHXgCcP99K6-ljb14N7pc3xptwMeSU2JDs61w3HV4eF31Hkc3wSmeNO3aA8E42Xt5c_O9I5gUFroBqNTwekRAvWFfRj4sKCWCcbChU7D-Po-g6hoc2UI7w7gxQDiq_VPK1hKG3PHvpikyWDM8H4RP9znD63uZqORVhVKB]--></g></svg>