---
type: "doc"
source: "source/exchanging-rest.html"
---
\[%settitle Exchanging with FHIR REST%\] \[%file newheader%\] \[%file newnavbar%\]

## Exchanging with FHIR REST

| Responsible Owner: [\[%wgt fhir%\]]([%wg fhir%]) Work Group | [Standards Status](versions#std-process):[Informative](versions#std-process) |
| --- | --- |

This page summarizes all of the FHIR simple RESTful actions that are not covered by [search](exchanging-search) or [operation](exchanging-operation) pages. There are three primary patterns for simple RESTful interactions - the [pull pattern](#pull), the [push pattern](#push) and the [asynchronous pattern](#async). Each RESTful action will support either push or pull and might also support asynchronous.

This specification is focused only on managing requesting information and/or pushing information. It is not intended to cover all data exchange scenarios (e.g., it does not deal with requests for action such as fulfillment of a request/order)

### pull

In this mode, the _data consumer_ is the initiator. It executes a GET HTTP command against a specified endpoint on the _data source_. The data source then returns the requested data. The main difference between this pattern and [search](exchanging-search) is that this simple pattern only returns a single matching resource, rather than a [Bundle](bundle) of possible matches.

\[%file rest-read.svg %\]

If successful, the response is an HTTP 200, along with the requested resource instance. If there is a failure, an appropriate HTTP error code will be provided, along with an optional [OperationOutcome](operationoutcome).

### push

There are many RESTful actions that follow this same basic pattern. A resource of some type (or a set of deltas from an existing resource) is transmitted from _data source_ to _data consumer_ using a simple REST command and the appropriate endpoint. The _data consumer_ either stores the data as requested (and acknowledges that success with an appropriate HTTP code) or it rejects the request. If accepted, a new 'version' of the resource is persisted at the specified endpoint and can potentially be referenced by other resources or subsequently queried or further manipulated. This basic pattern is shown in the diagram below:

\[%file rest.svg %\]

### async

This pattern is used for a subset of the [push](#push) scenarios. The request goes from the _data consumer_ to the _data source_, but the requested action does not complete immediately. Instead, the _data source_ delivers the response later. The _data consumer_ polls to see what the results are. This will be most commonly used with the [Bundle](bundle)\-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 [pull](#pull) transactions like [read](#read) or [vread](#vread). However no known use case exists for these simple operations to happen asynchronously.

\[%file rest-async.svg %\]

**Step 1:** The invocation of the RESTful action asynchronously is identical to synchronous invocation, with the exception that the `Prefer` 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.

**Step 2:** The _data consumer_ [polls](exchanging-polling) 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 _data consumer_ could also [cancel](async#3.1.6.3) the action, though cancellation of a state-changing action is not guaranteed).

**Step 3:** Once the action is complete, the response to the _data consumer_'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.

**Step 4:** The _data consumer_ retrieves the identified file or files from the _data source_, giving it confirmation of whether the requested action was successful.

### Actions

The following sections describe the different RESTful actions and indicate which pattern (or patterns) they follow.

#### RESTful read

[read](http#read) follows the [pull](#pull) pattern and uses a GET of the form `[base]/[resourceType]/[id]`. If successful, the _data consumer_ will receive the current version of the specified resource from the _data source_. Asynchronous is not expected to be relevant.

#### Version-specific read (vread)

[vread](http#vread) also follows the [pull](#pull) pattern and uses a GET of the form `[base]/[resourceType]/[id]/_history/[version]`. If successful, the _data consumer_ will receive the specified version of the resource with the specified id from the _data source_. Asynchronous is not expected to be relevant.

#### RESTful create

A [create](http#create) follows the [push](#push) pattern and uses the POST HTTP command to the `[base]/[resourceType]` endpoint to transmit a single resource from the _data source_, causing it to be stored on the _data consumer_. If successful, the requested record will be persisted at the RESTful endpoint of the _data consumer_ 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 [If-none-exist](http#ccreate) header. The response might include a copy of what was actually stored (which could be different than what was transmitted), an [OperationOutcome](operationoutcome) with any warning or information messages, or just the metadata indicating id and the version created. While [asynchronous](#async) use is theoretically possible, it would be uncommon for a create to take so long that synchronous operation was not possible.

#### RESTful update

A [update](http#update) follows the [push](#push) pattern and uses the PUT HTTP command to the `[base]/[resourceType]/[id]` endpoint to transmit a single resource from the _data source_, causing it to be stored on the _data consumer_ with the specified resource id. This is typically done to replace an existing version of the resource, but it can [also be used](http#upsert) to create a brand new record if there was no prior resource at that location and the _data consumer_ permits. Some servers might also support [conditional update](http#cupdate) using the `[base]/[resourceType]?[search parameters]` URL to create or update a resource where the id is unknown.

If successful, the requested record will be persisted at the RESTful endpoint of the _data consumer_ 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 [OperationOutcome](operationoutcome) 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 [If-match](http#concurrency) header. While [asynchronous](#async) use is theoretically possible, it would be uncommon for an update to take so long that synchronous operation was not possible.

The workflow for update may be a bit more complex with a [search](exchanging-search) happening prior to the update, particularly if conditional updates aren't supported.

#### Using Patch

[Patch](http#patch) works identically to [update](#update), with the exception that rather than sending the whole resource as the body, the _data source_ only sends a differential with what is believed to be the current version of the resource. The content transmitted is either a [JSON Patch](https://tools.ietf.org/html/rfc6902), [XMLPatch](http://tools.ietf.org/html/rfc5261) or [FHIRPath Patch](fhirpatch). The pattern, URLs, and supported headers, as well as the potential responses are the same as for Update.

#### Executing batches

Processing a [batch](http#transaction) follows the [Push](#push) pattern, though the [Asynchronous](#async) pattern is also appropriate in some cases. The [Bundle](bundle) with type 'batch' is POSTed to the `[base]` endpoint. The response will also be a Bundle, this time with a type of 'batch-response'. There is no paging capability for batches, though obviously a _data source_ could choose to transmit multiple small batches rather than a single 'big' batch. Because there are no dependencies between elements within a batch, size can be adjusted as need-be. (Though if actions are dependent on prior results, those would have to be sent in a separate batch - one where the previous results can be determined before submitting the second batch.)

#### Executing batch searches

A 'search' batch is the same as any other type of [batch](#batch). It is just that in a search batch, all the requested actions are different types of [search](exchanging-search). The roles are also reversed, in that the batch is initiated by the _data consumer_ on the server of the _data source_. 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.)

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.

#### Executing transactions

Processing a [transaction](http#transaction) is much the same as processing a [batch](#batch). The main differences are that the input must be a 'transaction' [Bundle](bundle) and the response will be a 'transaction-response'. The behavior is the same - the primary difference is giving guidance to the server on what sort of processing to perform, and the fact that a transaction response cannot contain failure entries.

#### Sharing documents

When manipulated RESTfully, creating or updating a document simply uses the [create](#create) or [update](#update) process with a base endpoint using the [Bundle](bundle) endpoint. There main difference is that the Bundle must adhere to the rules for a [FHIR document](documents). However, in addition to being stored RESTfully, FHIR documents can be transported other ways - by email, FTP, USB stick, etc. In some environments they might also be persisted as a [Binary](binary) if they are being stored alongside PDFs and other non-FHIR documents. In such cases, a [DocumentReference](documentreference) might be created alongside the Binary to provide searchable metadata to help locate the document. (DocumentReference can also be used when the document is stored as a Bundle rather than a Binary.)

#### Sharing collections

Like [documents](#document), creating or updating a collection simply uses the [create](#create) or [update](#update) process with a base endpoint using the [Bundle](bundle) endpoint. (Documents and collections are stored in the same place). However, unlike documents, which can be queried by chaining into their [Composition](composition) resource, there are limited mechanisms to search on the content of a 'collection' Bundle without defining custom search parameters. Also, like documents, FHIR collections can also be transported in other ways such as email, FTP, USB stick, etc. They are not, however, typically stored as [Binary](binary) instances or referenced by [DocumentReference](documentreference), though such uses are not prohibited.

\[%file newfooter%\]