<!DOCTYPE HTML>


[%settitle RESTful API%]
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
[%file newheader%]
</head>
<body>
[%file newnavbar%]

<div class="col-9">

<h2>RESTful API</h2>
<table class="cols"><tr><td id="wg"><a _target="blank" href="[%wg fhir%]">[%wgt fhir%]</a> Work Group</td><td id="fmm"><a href="resource.html#maturity">Maturity Level</a>: N/A</td><td id="ballot"><a href="help.html#status">Ballot Status</a>: <a href="history.html#pubs">DSTU 2</a></td></tr></table>

<p>
Each "resource type" has the same set of interactions defined that can be used to manage the resources
in a highly granular fashion. Applications claiming conformance to this framework
claim to be conformant to "RESTful FHIR"  (see <a href="conformance-rules.html">Conformance</a>).
</p>
<p>
Note that in this RESTful framework, transactions are performed directly on the server resource using an
HTTP request/response. The API does not directly address authentication, authorization, and audit
collection - for further information, see the <a href="security.html">Security Page</a>.
</p>
<p>
The API describes the FHIR resources as a set of operations (known as "interactions") on resources where 
individual resource instances are managed in collections by their type. Servers can choose which of
these interactions are made available and which resource types they support. Servers SHALL
provide a <a href="conformance.html">conformance statement</a> that specifies which interactions and
resources are supported.
</p>
<p>
The following logical interactions are defined:
</p>
<a name="interactions"> </a>
<a name="operations"> </a>
<table class="list">
  <tr><td><b>Instance Level Interactions</b></td><td></td></tr>
  <tr><td><a href="#read">read</a></td><td>Read the current state of the resource</td></tr>
  <tr><td><a href="#vread">vread</a></td><td>Read the state of a specific version of the resource</td></tr>
  <tr><td><a href="#update">update</a></td><td>Update an existing resource by its id (or create it if it is new)</td></tr>
  <tr><td><a href="#delete">delete</a></td><td>Delete a resource</td></tr>
  <tr><td><a href="#history">history</a></td><td>Retrieve the update history for a particular resource</td></tr>
  <tr><td colspan="2"><b>Type Level Interactions</b></td></tr>
  <tr><td><a href="#create">create</a></td><td>Create a new resource with a server assigned id</td></tr>
  <tr><td><a href="#search">search</a></td><td>Search the resource type based on some filter criteria</td></tr>
  <tr><td><a href="#history">history</a></td><td>Retrieve the update history for a particular resource type</td></tr>
  <tr><td colspan="2"><b>Whole System Interactions</b></td></tr>
  <tr><td><a href="#conformance">conformance</a></td><td>Get a conformance statement for the system</td></tr>
  <tr><td><a href="#transaction">batch/transaction</a></td><td>Update, create or delete a set of resources in a single interaction</td></tr>
  <tr><td><a href="#history">history</a></td><td>Retrieve the update history for all resources</td></tr>
  <tr><td><a href="#search">search</a></td><td>Search across all resource types based on some filter criteria</td></tr>
</table>
<p>In addition to these interactions, there is an <a href="operations.html">operations framework</a>, which includes endpoints
for <a href="operation-resource-validate.html">validation</a>, <a href="messaging.html#mailbox">messaging</a> and <a href="documents.html#bundle">Documents</a>.</p>

<p><b>Style Guide</b></p>
<p>
The interactions on this page are defined like this:
</p>

<pre>
  VERB [base]/[type]/[id] {?_format=[mime-type]}
</pre>
<ul>
 <li>The first word is the HTTP verb used for the interaction</li>
 <li>Content surrounded by [] is mandatory, and will be replaced by the string literal identified. Possible insertion values:
   <ul>
     <li><code>base</code>: The <a href="#root">Service Root URL</a></li>
     <li><code>mime-type</code>: The <a href="#mime-type">Mime Type</a></li>
     <li><code>type</code>: The name of a resource type (e.g. "Patient")</li>
     <li><code>id</code>: The <a href="resource.html#id">Logical Id</a> of a resource</li>
     <li><code>vid</code>: The <a href="resource.html#metadata">Version Id</a> of a resource</li>
     <li><code>compartment</code>: The name of a <a href="compartments.html#compartment">compartment</a></li>
     <li><code>parameters</code>: URL parameters as defined for the particular interaction</li>
   </ul>
 </li>
 <li>Content surrounded by <code>{}</code> is optional</li>
</ul>
<p>
Implementations constructing URLs using these patterns SHOULD conform to <a href="https://tools.ietf.org/html/rfc3986#appendix-A">RFC 3986 Section 6 Appendix A</a>
which requires percent-encoding for a number of characters that occasionally appear in the URLs (mainly in search parameters).
</p>
<p>
This specification uses the undescore as a prefix to disambiguate reserved names from other names in 3 cases:
</p>
<ul>
 <li>To differentiate system wide history and search interactions from interactions on Resource Types</li>
 <li>To differentiate search, history and similar interactions from instances of a resource type</li>
 <li>To differentiate search parameters defined for all reosurces from those defined for specific resource types</li>
</ul>
<p>
In addition, the character <code>$</code> is used as a prefix to operation names that are RPC-like additions to the base
API defined, either by this specification or by implementers.
</p>

<a name="root"> </a>
<a name="general"> </a>
<h3>Service Root URL</h3>
<p>
The Service Root URL is the address where all of the
resources defined by this interface are found. The Service
Root URL takes the form of
</p>
<pre>
http(s)://server{/path}
</pre>
<p>
The path portion is optional, and does not include a trailing slash. Each
resource type defined in this specification has a manager (or "entity set")
that lives at the address <code>/[type]</code> where the
<code>[type]</code> is the name of the resource type.
For instance, the resource manager for the type
<code>Patient</code> will live at:
</p>
<pre>
https://server/path/Patient
</pre>
<p>
All the logical interactions are defined relative to the service root
URL. This means that if the address of any one FHIR resource on a system
is known, the address of other resources may be determined.
</p>
<p>
Note: All URLs (and ids that form part of the URL) defined by this specification are case sensitive.</p>
<p>
Note that a server may use a path of the form <code>http://server/...[xx]...</code> where the <code>[xx]</code> is some variable
portion that identifies a particular instantiation of the FHIR API. Typically, the variable id
identifies a patient or a user, and the underlying information is completely compartmented
by the logical identity associated with <code>[xx]</code>. In this case, the FHIR API presents a
patient or user centric view of a record, where authentication/authorization is
explicitly granted to the URL, on the grounds that some identifiable user is associated
with the logical identity. It is not necessary to explicitly embed the patient id in the
URL - implementations can associate an FHIR end-point with a particular patient or
provider by using an OAuth login. See <a href="compartments.html#compartments">Compartments</a> for the logical underpinning.
</p>
<p><b>Identity</b></p>
<p>
Systems often need to compare two URLs to determine whether they refer to the same underlying object or not.
For the purposes of this specification, the following rules apply:
</p>
<ul>
 <li>The query part of the URL (anything after <code>?</code>) is ignored</li>
 <li>The comparison of the document portion of the URL (i.e. not the server/port) is case sensitive</li>
 <li>The protocols <code>http:</code> and <code>https:</code> SHALL NOT be used to refer to different underlying objects</li>
 <li>If a port is specified, then the ports must be identical or the objects are different (due to 
   the prevalence of port mapping and/or interface engines running on different ports). Ports should 
	 only be explicit when they have explicit meaning to the server</li>
</ul>
<p>
For example:
<code>http://myserver.com/patient/1</code> and <code>https://myserver.com/patient/1</code> refer to the same underlying object, while <code>http://myserver.com:81/patient/1</code> is a distinct entity from either of the above.
This does not mean that the two addresses need to be treated the same, or that a server must serve both addresses, or that the content from the two addresses must be identical, but just that if these two 
addresses have the same identity, and if both are served, they must both represent the same underlying object. Systems are not required to 
check that this is true. Note: the identity comparison for protocols other than http:/https: is undefined.
</p>

<h3>Resource Metadata and Versioning</h3>
<p>
Each resource has an associated set of <a href="resource.html#metadata">resource metadata elements</a>. These map to the HTTP request and response using the following fields:
</p>
<table class="grid">
  <tr><th>Metadata Item</th><th>Where found in HTTP</th></tr>
  <tr><td><a href="resource.html#id">Logical Id (.id)</a></td><td>The Id is represented explicitly in the URL</td></tr>
  <tr><td><a href="resource.html#metadata">Version Id (.meta.versionId)</a></td><td>The Version Id is represented in the <code>ETag</code> header</td></tr>
  <tr><td><a href="resource.html#metadata">Last modified (.meta.lastUpdated)</a></td><td>HTTP Last-Modified header</td></tr>
</table>
<p>Note that the Version Id is considered a "weak" ETag and <code>ETag</code> headers
	should be prefixed with <code>W/</code> and enclosed in quotes, for example:</p>
<pre>
ETag: W/"3141"
</pre>
<h3>Security</h3>
<p>
Using HTTPS is optional, but all production exchange of healthcare data SHOULD use SSL and 
additional security as appropriate. See <a href="security.html#http">HTTP Security</a> for further information.
Most operations will require user authentication, and all operations that do are subject 
to <a href="https://en.wikipedia.org/wiki/Role-based_access_control">RBAC</a> and/or <a href="https://en.wikipedia.org/wiki/Attribute-based_access_control">ABAC</a>,
and some operations may depend on appropriate consent being granted. 
</p>
<p>
The choice of whether to return <code>403</code> Unauthorised or <code>404</code> Not found depends upon 
the specific situation and specific local policies, regulations, and laws. The 
decision of which error to use will include consideration of whether disclosure 
of the existence of relevant records is considered an acceptable disclosure of 
PHI (Personal Health Information) or a prohibited disclosure of PHI. Note 
that since a <code>404</code> does not leak information, it should be the default choice 
unless there is a specific reason to return a <code>403</code>.
</p>
<p>
Note: to support browser-based client applications, recommend that servers SHOULD implement <a href="http://enable-cors.org/">cross-origin resource sharing</a> for the interactions documented here.
Experience shows that this is an area where ongoing issues may be expected as security holes are found and closed in an ongoing basis.
</p>

<h3>HTTP Status Codes</h3>
<p>
This specification makes rules about the use of specific HTTP status codes
in particular circumstances where the status codes SHALL map to particular
states correctly, and only where the correct status code is not obvious.
Other HTTP status codes may be used for other states as appropriate, and this particularly
includes various authentication related status codes and redirects.
Authentication redirects should not be interpreted to change the location
of the resource itself (a common web programming error).
</p>
<p>
FHIR defines an <a href="operationoutcome.html">OperationOutcome resource</a> that can be used to convey specific detailed
processable error information. For a few combinations of interactions and specific
return codes, an OperationOutcome is required to be returned as the content of the response.
The OperationOutcome may be returned with any HTTP <code>4xx</code> or <code>5xx</code> response, but is not required - many of
these errors may be generated by generic server frameworks underlying a FHIR server.
</p>
<a name="return"> </a>
<h3>Managing Return Content</h3>
<p>
In the interests of managing band-width, this specification allows clients
to specify what kind of content to return.
</p>
<a name="cread"> </a>
<h4>conditional read</h4>
<p>
Clients may use the <code>If-Modified-Since</code>, or <code>If-None-Match</code> HTTP header on a <code>read</code> request.
If so, they MUST accept either a <code>304</code> Not Modified as a valid status code on the response (which means that the
content is unchanged since that date) or full content (either the content has not changed,
or the server does not support conditional request).
</p>
<p>
Servers can return <code>304</code> Not Modified where content is unchanged since the
<code>If-Modified-Since</code> date-time or the <code>If-None-Match</code> ETag specified or they can
return the full content as normal. This optimisation is relevant in reducing bandwidth for caching purposes and servers are encouraged but
not required to support this. If servers don't support conditional read, they just return the full content.
</p>
<h4>create/update/transaction</h4>
<p>
These interactions are performed using <code>POST</code>,<code>PUT</code> and <code>POST</code> respectively, and
it may be appropriate for a server to return either only a status
code, or also return the entire resource that is the outcome of the
create or update (which may be different to that provided by the
client). In the case of transactions this means returning a Bundle with just the <code>Bundle.entry.response</code> populated for each entry,
and not the <code>Bundle.entry.resource</code> values.
</p>
<a name="prefer"> </a>
<p>The client can indicate whether the entire resource is
returned using the <a href="https://tools.ietf.org/html/rfc7240#section-4.2">HTTP
return preference</a>:
</p>
<pre>
Prefer: return=minimal
Prefer: return=representation
</pre>
<p>
The first of these two asks to return no body. The
second asks to return the full resource. Servers SHOULD honor this header.
In the absence of the header, servers may choose whether to return the
full resource or not. Note that this setting only applies to succesful interactions.
In case of failure, servers SHOULD always return a body that contains an 
<a href="operationoutcome.html">OperationOutcome</a> resource.
</p>

<a name="mime-type"> </a>
<h3>Content Types and encodings</h3>
<p>
The formal MIME-type for FHIR resources is <code>application/xml+fhir</code> or <code>application/json+fhir</code>.
The correct mime type SHALL be used by clients and servers:
</p>
<ul>
 <li>XML: <code>application/xml+fhir</code></li>
 <li>JSON: <code>application/json+fhir</code></li>
</ul>
<p>
Servers SHALL support server-driven content negotiation
as described in <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12">section 12</a>
of the HTTP specification. 
</p>
<p>
However in order to support various implementation limitations, servers SHOULD
support the optional <code>_format</code> parameter to specify alternative response formats by their MIME-types.
This parameter allows a client to override the <code>accept</code> header value when it is unable to set it correctly
due to internal limitations (e.g. XSLT usage).
For the <code>_format</code> parameter, the values <code>xml</code>, <code>text/xml</code>, <code>application/xml</code>, and <code>application/xml+fhir</code> SHALL be interpreted to mean
the normative XML format defined by FHIR and <code>json</code>, <code>application/json</code> and <code>application/json+fhir</code> SHALL be interpreted to mean the
informative JSON format. In addition, the values <code>html</code> and <code>text/html</code> are allowed.
</p>
<p>
FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1)
defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set
the character encoding to UTF-8 using the <code>charset</code> parameter of the MIME-type in the <code>Content-Type</code> header.
Requests MAY also specify this <code>charset</code> parameter in the <code>Accept</code> header and/or use the <code>Accept-Charset</code> header.
</p>
<p>
Note: the <code>_format</code> parameter does not override the <code>content-type</code> header.
</p>
<p>
The content types <code>application/x-www-form-urlencoded</code> is also accepted for posting <code>search</code> requests.
</p>

<a name="versioning"> </a>
<h3>Support for Versions</h3>
<p>
Servers that support this API SHOULD provide full version support - that is, populate and track
<code>versionId</code> correctly, support <code>vread</code>, and implement <a href="#versionaware">version aware updates</a>.
Supporting versions like this allows for related systems to track the correct version of information,
and to keep integrity in clinical records. However, many current operational systems do not
do this, and cannot easily be re-engineered to do so.
</p>
<p>
For this reason, servers are allowed to not provide versioning support and this API does not enforce
that versioning is supported. Clients may elect to only interact with servers that do provide full
versioning support. Systems declare their support for versioning
in their <a href="conformance-definitions.html#Conformance.rest.resource.noVersion">conformance statement</a>.
</p>
<p>
Server should always return the default timezone for <a href="search.html#date">date searches</a> 
in the HTTP Response headers using the Date header. Note: Servers are not required to have a 
default timezone.
</p>

<a name="read"> </a>
<h3>read</h3>
<p>
The <code>read</code> interaction accesses the current contents of a resource. The interaction
is performed by an HTTP <code>GET</code> command as shown:
</p>
<pre>
  GET [base]/[type]/[id] {?_format=[mime-type]}
</pre>
<p>
This returns a single instance with the content specified for the resource type.
This url may be accessed by a browser. The possible values for the
<a href="resource.html#id">Logical Id</a> ("id") itself are described in the <a href="datatypes.html#id">id type</a>.
The returned resource SHALL have an <code>id</code> element with a value that is the [id].
Servers SHOULD return an <code>ETag</code> header with the versionId of the resource (if versioning is supported) and a <code>Last-Modified</code> header.
</p>
<p>
Note: Unknown resources and deleted resources are treated differently on a read: A <code>GET</code> for a deleted
resource returns a <code>410</code> status code, whereas a <code>GET</code> for an unknown resource returns <code>404</code>. Systems that do
not track deleted records will treat deleted records as an unknown resource. Since deleted resources may be brought 
back to life, servers MAY include an ETag on the error response when reading a deleted record to allow version 
contention management when a resource is brought back to life. 
</p>

<p>
In addition, the search parameter <code>_summary</code> can be used when reading a resource:
</p>
<pre>
  GET [base]/[type]/[id] {?_summary=text}
</pre>
<p>
This requests that only a subset of the resource content be returned,
as specified in the <code>_summary</code> parameter, which can have the values 
<a href="search.html#summary"><code>true</code>, <code>false</code>, <code>text</code> &amp; <code>data</code></a>.
Note that a resource that only contains a subset of the data is 
not suitable for use as a base to update the resource, and may not 
be suitable for other uses. Servers SHOULD use the <a href="v3/vs/SecurityIntegrityObservationValue/index.html#SUBSETTED">SUBSETTED</a> <a href="security-labels.html">Security Label</a>
to explicitly mark such resources.
</p>

<a name="vread"> </a>
<h3>vread</h3>
<p>
The <code>vread</code> interaction preforms a version specific read of the resource. The interaction
is performed by an HTTP <code>GET</code> command as shown:
</p>
<pre>
  GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}
</pre>
<p>
This returns a single instance with the content specified for the resource type for that
version of the resource.
The returned resource SHALL have an <code>id</code> element with a value that is the <code>[id]</code>, and a <code>meta.versionId</code>
element with a value of <code>[vid]</code>. Servers SHOULD return an <code>ETag</code> header with the versionId (if versioning is supported) 
and a <code>Last-Modified</code> header.
</p>
<p>
The <a href="resource.html#metadata">Version Id</a> ("vid") is an opaque identifier that conforms to the same <a href="datatypes.html#id">format requirements</a> as
a <a href="resource.html#id">Logical Id</a>. The id may have been found by performing a history interaction (see below), by recording the
version id from a content location returned from a <code>read</code> or from a version specific reference in a
content model. If the version referred to is actually one where the resource was deleted, the
server should return a <code>410</code> status code.
</p>
<p>
Servers are encouraged to support a version specific retrieval of the current version of the
resource even if they do not provide access to previous versions. If a request
is made for a previous version of a resource, and the server does not support accessing
previous versions, it should return a <code>404</code> Not Found error, with an operation outcome
explaining that history is not supported for the underlying resource type.
</p>

<a name="update"> </a>
<h3>update</h3>
<p>
The <code>update</code> interaction creates a new current version for an existing resource or
creates an initial version if no resource already exists for the given id.
The <code>update</code> interaction is performed by an HTTP <code>PUT</code> command as shown:
</p>
<pre>
  PUT [base]/[type]/[id] {?_format=[mime-type]}
</pre>
<p>
The request body SHALL be a <a href="resource.html">Resource</a> with an id element 
that has an identical value to the <code>[id]</code> in the URL. If no <code>id</code> element is provided, or 
the value is wrong, the server SHALL respond with a HTTP <code>400</code> error code, and SHOULD
provide an operation outcome identifying the issue.
If the request body includes a <a href="resource.html#meta"><code>meta</code></a>, the server SHALL
ignore the existing <code>versionId</code> and <code>lastUpdated</code> values.

If the server supports versions, it SHALL populate the <code>meta.versionId</code> and <code>meta.lastUpdated</code>
with the new correct values. Servers are allowed to review and alter the other metadata values, but SHOULD refrain
from doing so (see <a href="resource.html#meta">metadata description</a>  for further information).
</p>
<p>
A server SHOULD accept the resource as submitted when it accepts the update, and return the same
content when it is subsequently read. However systems may not be able to do this; see
the note on <a href="#transactional-integrity">transactional integrity</a> for discussion.
Also, see <a href="updates.html">Variations between Submitted data and Retrieved data</a> for additional discussion
around update behavior.
</p>
<blockquote class="dstu-note">
<a name="dstu"> </a>
<p>
<b>DSTU Note:</b>   The update operation updates the entire resource. Servers MAY apply some logic
and preserve some existing content based where this is known to be appropriate behavior. 
HTTP <code>PATCH</code> functionality is likely to be defined, and feedback from outcomes of implementer
experimentation is welcome. 
</p>
<p>
Provide feedback <a href="http://wiki.hl7.org/index.php?title=FHIR_Specification_Feedback_(DSTU_2)">here</a>.
</p>
</blockquote>
<p>
If the interaction is successful, the server SHALL return either a <code>200</code> OK HTTP status code if the resource was updated, or a <code>201</code> Created status code if the resource was created,
with a <code>Last-Modified</code> header, and an <code>ETag</code> header which contains the new <code>versionId</code> of the resource. If the resource was created (i.e. the interaction resulted in a <code>201</code> Created), the server SHOULD
return a <code>Location</code> header (this is for HTTP conformance; it's not otherwise needed).
</p>
<p>
Note: Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace when accepting updates, but are not required to do so. The impact of this on digital signatures may need to be considered.
</p>
<p>
Note that servers MAY choose to allow clients to <code>PUT</code> a resource to a location that 
does not yet exist on the server - effectively, allowing the client to define the 
id of the resource. Whether a server allows this is a deployment choice based 
on the nature of its relationships with the clients. While many servers will 
not allow clients to define their ids, there are several reasons why it may
be necessary in some configurations:
</p>
<ul>
 <li>client is reproducing an existing data model on the server, and needs to keep original ids in order to retain ongoing integrity</li>
 <li>client is a server doing push based pub/sub (this is a special case of the first reason)</li>
 <li>multiple clients doing push in the context of agreed data model shared across multiple servers where ids are shared across servers</li>
</ul>
<p>
Alternatively, clients may be sharing an agreed identification model (e.g. key server, scoped identifiers, or UUIDs)
where clashes do not arise.
</p>
<p>
Servers can choose whether or not to support client defined ids, and indicate such to the clients 
using <a href="conformance-definitions.html#Conformance.rest.resource.updateCreate">Conformance.rest.resource.updateCreate</a>.
</p>

<h4>Rejecting Updates</h4>
<p>
Servers are permitted to reject update interactions because of integrity concerns or other business rules, and return HTTP status codes accordingly (usually a <code>422</code>).
</p>
<p>
Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):
</p>
<ul>
 <li><b><code>400</code> Bad Request</b> - resource could not be parsed or failed basic FHIR validation rules (or multiple matches were found for </li>
 <li><b><code>403</code> Not Authorized</b> - authorization is required for the interaction that was attempted</li>
 <li><b><code>404</code> Not Found</b> - resource type not supported, or not a FHIR end-point</li>
 <li><b><code>405</code> Method Not allowed</b> - the resource did not exist prior to the update, and the server does not allow client defined ids</li>
 <li><b><code>409</code>/<code>412</code></b> - version conflict management - see <a href="#concurrency">below</a></li>
 <li><b><code>422</code> Unprocessable Entity</b> - the proposed resource violated applicable FHIR profiles or server business rules</li>
</ul>
<p>
Any of these errors SHOULD be accompanied by an <a href="operationoutcome.html">OperationOutcome</a> resource providing additional detail concerning the issue.
</p>
<p>
For additional information on how systems may behave when processing updates, refer to the <a href="updates.html">Variations between Submitted data and Retrieved data</a> page.
</p>

<h4>Conditional update</h4>
<p>
The conditional update interaction allows a client to update an existing resource based on some identification criteria,
rather than by  <a href="resource.html#meta">logical id</a>. To accomplish this, the client issues a <code>PUT</code> as shown:
</p>
<pre>
  PUT [base]/[type]/?[search parameters]
</pre>
<p>
When the server processes this update, it performs a search using its standard
<a href="search.html">search facilities</a> for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends
on how many matches are found:
</p>
<ul>
 <li><b>No matches</b>: The server performs a <a href="#create"><code>create</code></a> interaction</li>
 <li><b>One Match</b>: The server performs the update against the matching resource</li>
 <li><b>Multiple matches</b>: The server returns a <code>412</code> Precondition Failed error indicating the client's criteria were not selective enough</li>
</ul>
<p>
This variant can be used to allow a stateless client (such as an interface engine) to submit
updated results to a server, without having to remember the logical ids that the server has assigned.
For example, a client updating the status of a lab result from "preliminary" to "final"
might submit the finalized result using <code>PUT /Observation?identifier=http://my-lab-system|123</code>
</p>
<p>
Note that transactions and conditional create/update/delete are complex interactions and it is 
not expected that every server will implement them. Servers that don't support the conditional 
update should return an HTTP <code>400</code> error and an operation outcome.
</p>


<a name="versionaware"> </a>
<a name="concurrency"> </a>

<h3>Managing Resource Contention</h3>
<p>
<a href="http://www.w3.org/1999/04/Editing/">Lost Updates</a>, where two clients update the same
resource, and the second overwrites the updates of the first, can be prevented using a combination
of the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19">ETag</a> and
<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24">If-Match</a> header.
</p>
<p>
To support this usage, servers SHOULD always return an <code>ETag</code> header with each resource:
</p>
<pre class="http">
HTTP 200 OK
Date: Sat, 09 Feb 2013 16:09:50 GMT
Last-Modified: Sat, 02 Feb 2013 12:02:47 GMT
ETag: W/"23"
Content-Type: application/json+fhir
</pre>
<p>
If provided, the value of the ETag SHALL match the value of the version id for the resource. Servers
are allowed to generate the version id in whatever fashion that they wish, so long
as they are valid according to the <a href="datatypes.html#id">id</a> data type,
and are unique within the address space of all versions of the same resource.
When resources are returned as part of a bundle, there is no ETag, and the
versionId of the resource is used directly.
</p>
<p>
If the client wishes to request a version aware update, it submits the request with an
<code>If-Match</code> header that quotes the ETag from the server:
</p>
<pre class="http">
PUT /Patient/347 HTTP/1.1
If-Match: W/"23"
</pre>
<p>
If the version id given in the <code>If-Match</code> header does not match, the server returns a
<code>409 Conflict</code> status code instead of updating the resource.
</p>
<p>
Servers can require that clients provide an <code>If-Match</code> header by returning <code>412 Pre-condition failed</code>
status codes when no <code>If-Match</code> header is found.
</p>


<a name="delete"> </a>
<h3>delete</h3>
<p>
The <code>delete</code> interaction removes an existing resource. The interaction
is performed by an HTTP <code>DELETE</code> command as shown:
</p>
<pre>
  DELETE [base]/[type]/[id]
</pre>
<p>
A delete interaction means that subsequent <a href="#read">non-version specific reads</a> of a resource
return a <code>410</code> HTTP status code and that the resource is no longer found through <a href="#search">search</a>
interactions. Upon successful deletion, or if the resource does not exist at all, the server should return
<code>204 No Content</code>. <!--, or 200 OK status code, with an <a href="operationoutcome.html">OperationOutcome</a>
resource containing hints and warnings about the deletion; if one is sent it SHALL NOT include any errors. -->
</p>
<p>
Whether to support delete at all, or for a particular resource type or a particular instance is at the 
discretion of the server based on the business rules that apply in its context.  
If the server refuses to delete resources of that type as a blanket policy, then it should return the <code>405</code>
Method not allowed status code. If the server refuses to delete a resource because of reasons specific
to that resource, such as referential integrity, it should return the <code>409</code> Conflict status code.
Performing this interaction on a resource that is already deleted has no effect, and the server should return a <code>204</code> or <code>200</code> response.
Resources that have been deleted may be "brought back to life" by a subsequent <a href="#href"><code>update</code></a> interaction using an HTTP <code>PUT</code>.
</p>
<p>
Many resources have a status element that overlaps with the idea of deletion. Each resource type
defines what the semantics of the deletion interactions are. If no documentation is provided, the
deletion interaction should be understood as deleting the record of the resource, with nothing
about the state of the real-world corresponding resource implied.
</p>
<p>
For servers that maintain a version history, the <code>delete</code> interaction does not remove a resource's version history. From a version history respect,
deleting a resource is the equivalent of creating a special kind of history entry that has
no content and is marked as deleted.
</p>
<p>
Since deleted resources may be brought back to life, servers MAY include an ETag on the delete response
to allow version contention management when a resource is brought back to life. 
</p>

<h4>Conditional delete</h4>
<p>
The conditional delete interaction allows a client to delete an existing resource based on some selection criteria,
rather than by a specific <a href="resource.html#meta">logical id</a>. To accomplish this, the client issues an HTTP <code>DELETE</code> as shown:
</p>
<pre>
  DELETE [base]/[type]/?[search parameters]
</pre>
<p>
When the server processes this delete, it performs a search as specified using the standard
<a href="search.html">search facilities</a> for the resource type. The action it takes depends
on how many matches are found:
</p>
<ul>
 <li><b>No matches</b>: The server returns <code>404</code> Not found</li>
 <li><b>One Match</b>: The server performs an ordinary <code>delete</code> on the matching resource</li>
 <li><b>Multiple matches</b>: Servers may choose to delete all the matching resources, or it may choose to return a <code>412</code> Precondition Failed error indicating the client's criteria were not selective enough.
   A server indicates whether it can delete multiple resources in its <a href="conformance-definitions.html#Conformance.rest.resource.conditionalDelete">Conformance Statement (.rest.resource.conditionalDelete)</a>.
   if there are multiple matches, either all must deleted, or the server SHALL return an error</li>
</ul>
<p>
This variant can be used to allow a stateless client (such as an interface engine) to delete
a resource on a  server, without having to remember the logical ids that the server has assigned.
For example, a client deleting a lab atomic result might delete the resource using <code>DELETE /Observation?identifier=http://my-lab-system|123</code>.
</p>
<p>
Note that transactions and conditional create/update/delete are complex interactions and it is 
not expected that every server will implement them. Servers that don't support the conditional 
delete should return an HTTP <code>400</code> error and an operation outcome.
</p>

<a name="create"> </a>
<h3>create</h3>
<p>
The <code>create</code> interaction creates a new resource in a server-assigned location. If the client
wishes to have control over the id of a newly submitted resource, it should use the <a href="#update">update</a>
interaction instead. The <code>create</code> interaction is performed by an HTTP <code>POST</code> command as shown:
</p>
<pre>
  POST [base]/[type] {?_format=[mime-type]}
</pre>
<p>
The request body SHALL be a FHIR Resource without an id element (this is the
only case where a resource exists without an id element). If an ID element is provided, the 
server SHALL respond with a HTTP <code>400</code> error code, and SHOULD provide an operation outcome 
identifying the issue.
If the request body includes a <a href="resource.html#meta">meta</a>, the server SHALL
ignore the existing <code>versionId</code> and <code>lastUpdated</code> values.
The server SHALL populate the <code>meta.versionId</code> and <code>meta.lastUpdated</code>
with the new correct values.
Servers are allowed to review and alter the other metadata values, but SHOULD refrain
from doing so (see <a href="resource.html#meta">metadata description</a>  for further information).
</p>
<p>
A server SHOULD accept the resource as submitted when it accepts the create, and return the same
content when it is subsequently read. However some systems may not be able to do this; see
the note on <a href="#transactional-integrity">transactional integrity</a> for discussion.
</p>
<p>
The server returns a <code>201</code> Created HTTP status code, and SHOULD also return a <code>Location</code> header which
contains the new <a href="resource.html#metadata">Logical Id</a> and <a href="resource.html#metadata">Version Id</a> of
the created resource version:
</p>
<pre>
  Location: [base]/[type]/[id]/_history/[vid]
</pre>
<p>
where <code>[id]</code> and <code>[vid]</code> are the newly created id and version id for the resource version.

Servers SHOULD return an <code>ETag</code> header with the versionId (if versioning is supported) and a <code>Last-Modified</code> header.
</p>
<p>
When the resource syntax or data is incorrect or invalid, and cannot be used to create a new resource, the server returns a <code>400</code> Bad Request HTTP status code.
When the server rejects the content of the resource because of business rules, the server returns a <code>422</code> Unprocessible Entity error HTTP status code.
In either case, the server SHOULD include a response body containing an <a href="operationoutcome.html">OperationOutcome</a> with detailed error messages describing the reason for the error.
</p>
<p>
Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):
</p>
<ul>
 <li><b><code>400</code> Bad Request</b> - resource could not be parsed or failed basic FHIR validation rules</li>
 <li><b><code>404</code> Not Found</b> - resource type not supported, or not a FHIR end-point</li>
 <li><b><code>422</code> Unprocessable Entity</b> - the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an <a href="operationoutcome.html">OperationOutcome</a> resource providing additional detail</li>
</ul>
<p>
Note: Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace when accepting creates, but are not required to do so. The impact of this on digital signatures may need to be considered.
</p>
<p>
For additional information on how systems may behave when processing updates, refer to the <a href="updates.html">Variations between Submitted data and Retrieved data</a> page.
</p>

<a name="ccreate"> </a>
<h4>Conditional create</h4>
<p>
The conditional <code>create</code> interaction allows a client to create a new resource only if some equivalent resource
does not already exist on the server. The client defines what equivalence means in this case by supplying
a FHIR search query in an <code>If-None-Exist</code> header as shown:
</p>
<pre>
  If-None-Exist: [search parameters]
</pre>
<p>
The parameter just contains the search parameters (what would be in the URL  following the "?").
</p>
<p>
When the server processes this create, it performs a search as specified using its standard
<a href="search.html">search facilities</a> for the resource type. The action it takes depends
on how many matches are found:
</p>
<ul>
 <li><b>No matches</b>: The server processes the create as above</li>
 <li><b>One Match</b>: The server ignore the post and returns <code>200</code> OK</li>
 <li><b>Multiple matches</b>: The server returns a <code>412</code> Precondition Failed error indicating the client's criteria were not selective enough</li>
</ul>
<p>
This variant can be used to avoid the risk of two clients
creating duplicate resources for the same record. For example, a client posting a new lab result might specify
<code>If-None-Exist: identifier=http://my-lab-system|123</code> to ensure it is does not create a duplicate record.
</p>
<p>
Note that transactions and conditional create/update/delete are complex interactions and it is 
not expected that every server will implement them. Servers that don't support the conditional 
create should return an HTTP <code>412</code> error and an operation outcome.
</p>


<a name="search"> </a>
<h3>search</h3>
<p>
This interaction searches a set of resources based on some filter criteria. The interaction can be performed by several different HTTP commands.
</p>
<pre>
  GET [base]/[type]{?[parameters]{&amp;_format=[mime-type]}}
</pre>
<p>
This searches all resources of a particular type using the criteria represented in the parameters. 
</p>
<p>
Because of the way that some user agents and proxies treat <code>GET</code> and <code>POST</code> requests, in addition
to the get based search method above, servers that support <i>search</i> SHALL also support a <code>POST</code> based search:
</p>
<pre>
POST  [base]/[type]/_search{?[parameters]{&amp;_format=[mime-type]}}
</pre>
<p>
This has exactly the same semantics as the equivalent <code>GET</code> command. All these search interactions take a series of parameters that
are a series of <code>name=value</code> pairs encoded in the URL (or as an <code>application/x-www-form-urlencoded</code> submission for a <code>POST</code>).
(See <a href="http://www.w3.org/TR/REC-html40/interact/forms.html#form-content-type">W3C HTML forms</a>).
</p>
<blockquote>
<p>
Note: <code>application/x-www-form-urlencoded</code> is supported for <code>POST</code> so that invoking a search by <code>GET</code> or <code>POST</code> can be 
done from HTML forms in a browser (though considerable active content might be required in the browser), although
this is not the main usage. 
</p>
</blockquote>
<p>
Searches are processed as specified for the <a href="search.html">Search handling mechanism</a>.
</p>
<p>
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 <a href="operationoutcome.html">OperationOutcome</a>.
If the search succeeds, the return content is a <a href="compartments.html#bundle">Bundle</a> with
<a href="bundle-definitions.html#Bundle.type">type</a> = <code>searchset</code> containing the results of the search as a list of resources
in a defined order. The result list can be long, so servers may use paging. If they do, they SHALL use the method <a href="#paging">described below</a>
(adapted from <a href="https://tools.ietf.org/html/rfc5005">RFC 5005 (Feed Paging and Archiving</a>) for breaking the
list into pages if appropriate. The server MAY also return an OperationOutcome resource with additional information about the search;
if one is sent it SHALL NOT include any errors, and it shall be marked with an <a href="valueset-search-entry-mode.html">entry
mode</a> of <code>include</code>.
</p>
<a name="vsearch"> </a>
<h4>Variant Searches</h4>
<p>
To search a <a href="compartments.html#compartments">compartment</a>, for either all possible resources or for a particular resource type, respectively:
</p>
<pre>
  GET [base]/[Compartment]/[id]/{*?[parameters]{&amp;_format=[mime-type]}}
  GET [base]/[Compartment]/[id]/[type]{?[parameters]{&amp;_format=[mime-type]}}
</pre>
<p>
For example, to retrieve all the observation resources for a particular LOINC code associated with a particular encounter:
</p>
<pre>
  GET [base]/Encounter/23423445/Observation?code=2951-2  {&amp;_format=[mime-type]}
</pre>
<p>
Note that there are specific operations defined to support fetching <a href="patient-operations.html#everything">an entire patient record</a>
or <a href="encounter-operations.html#everything">all record for an encounter</a>.
</p>
<p>
Finally, it's possible to search all resources at once:
</p>
<pre>
  GET [base]?[parameters]{&amp;_format=[mime-type]}
</pre>
<p>
When searching all resources at once, only the <a href="resource.html#search">parameters defined for all resources</a> 
can be used.
</p>


<a name="conformance"> </a>
<h3>conformance</h3>
<p>
The <code>conformance</code> interaction retrieves the server's conformance statement that defines how it supports resources.
The interaction is performed by an HTTP <code>OPTIONS</code> or a <code>GET</code> command as shown:
</p>
<pre>
  GET [base]/metadata {?_format=[mime-type]}
  OPTIONS [base] {?_format=[mime-type]}
</pre>
<p>
Applications SHALL return a <a href="conformance.html">Conformance Resource</a> that specifies which resource types and interactions are supported
for the <code>GET</code> command, and SHOULD do so for the <code>OPTIONS</code> command. If a <code>404</code> Unknown is returned from the <code>GET</code>, FHIR is not supported on the
nominated service url. The <code>GET</code> command is defined because not all client libraries are able to perform an <code>OPTIONS</code> command.
An <code>ETag</code> header SHOULD be returned with the conformance resource. The value of the header SHALL change if the
conformance statement itself changes. Additional parameters that are required to be returned with
the <code>OPTIONS</code> command are defined in the <a href="#hdata">OMG hData RESTful Transport</a> specification.
</p>
<p>
The Conformance statement returned typically has an arbitrary id, and no meta element, though it is not prohibited.
</p>
<p>
In addition to this <code>conformance</code> interaction, a server may also choose to provide the
standard set of interactions (<code>read</code>, <code>search</code>, <code>create</code>, <code>update</code>) defined on this page
for the <a href="conformance.html">Conformance Resource</a> end-point.
This is different from the <code>conformance</code> interaction:
</p>
<table class="grid">
 <tr><td><code>conformance</code> interaction</td><td>returns a conformance statement describing the server's current operational functionality</td></tr>
 <tr><td>conformance end-point</td><td>manages a repository of conformance statements (e.g. the HL7 conformance statement registry)</td></tr>
</table>
<p>
All servers are required to support the <code>conformance</code> interaction, but servers may choose whether they wish to support the conformance end-point, 
just like any other end-point.
</p>

<a name="transaction"> </a>
<h3>batch/transaction</h3>
<p>
The <code>batch</code> and <code>transaction</code> interactions submit a set of actions to perform on a server in a single HTTP request/response.
The actions may be performed independently as a "batch", or as a single atomic "transaction" where 
the entire set of changes succeed or fail as a single entity. Multiple actions on multiple resources 
of the same or different types may be submitted, and they may be a mix of other interactions defined 
on this page (e.g. <code>read</code>, <code>search</code>, <code>create</code>, <code>update</code>, <code>delete</code>, etc.), or using the <a href="operations.html">operations</a>
framework.
</p>
<p>
The <code>transaction</code> mode is especially useful where one would otherwise need multiple interactions, possibly
with a risk of loss of referential integrity if a later interaction fails (e.g. when storing
a Provenance resource and its corresponding target resource, or, on document repositories, a
document index entry and its accompanying document).
</p>
<p>
Note that transactions and conditional create/update/delete are complex interactions and it is 
not expected that every server will implement them.
</p>
<p>
A <code>batch</code> or <code>transaction</code> interaction is performed by an HTTP <code>POST</code> command as shown:
</p>
<pre>
  POST [base] {?_format=[mime-type]}
</pre>
<p>
The content of the post submission is a <a href="bundle.html">Bundle</a> with <a href="bundle-definitions.html#Bundle.type">Bundle.type</a> = <code><a href="valueset-bundle-type.html#batch">batch</a></code> or <code><a href="valueset-bundle-type.html#transaction">transaction</a></code>.
Each entry carries <code>request</code> details (<a href="bundle-definitions.html#Bundle.entry.request">Bundle.entry.request</a>)
that provides the HTTP details of the action in order to inform the system processing the batch or transaction
what to do for the entry. If the HTTP command is a <code>PUT</code> or <code>POST</code>, then the entry 
SHALL contain a resource for the body of the action.
The resources in the bundle are each processed separately as if they were an individual
interactions or operations as otherwise described on this page, or the <a href="operations.html">Operations
framework</a>. The actions are subject to the normal processing for each,
including the <a href="resource.html#meta">meta element</a>, verification and version aware updates,
and <a href="#transactional-integrity">transactional integrity</a>.
</p>
<p>
Examples:
</p>
<ul>
 <li><a href="bundle-transaction.html">Transaction</a></li>
 <li><a href="bundle-response.html">Matching Response</a></li>
</ul>

<h4>Batch Processing Rules</h4>
<p>
For a <code>batch</code>, there SHALL be no interpendencies between the different entries
in the Bundle. The success or failure of one entry SHALL not alter the sucess or failure
or resulting content of another. Servers SHALL validate that this is the case. 
Note that it is considered that servers execute the batch in the same order as 
that specified below for transactions, though the order of exceution should not 
matter given the previous rule.
</p>
<h4>Transction Processing Rules</h4>
<p>
For a <code>transction</code>, servers SHALL either accept all actions and return a <code>200</code> OK, along with a
response bundle (see below), or reject all resources and return an HTTP <code>400</code> or <code>500</code> type
response. It is not an error if the submitted bundle has no resources in it.
The outcome of the processing the transaction SHALL NOT depend on the order
of the resources in the transaction. A resource can only appear in a transaction
once (by identity).
</p>
<p>
Because of the rules that a transaction is atomic where all actions pass or fail
together and the order of the entries doesn't matter, there is a particular order in which to process the actions:
</p>
<ol>
 <li>Process any <code>DELETE</code> interactions</li>
 <li>Process any <code>POST</code> interactions</li>
 <li>Process any <code>PUT</code> interactions</li>
 <li>Process any <code>GET</code> interactions</li>
</ol>
<p>
If any resource identities (including resolved identities from conditional update/delete) overlap in steps 1-3, 
then the transaction SHALL fail. 
</p>
<blockquote class="dstu-note">
<a name="dstu-2"> </a>
<p>
<b>DSTU Note:</b>  clients are able to request that operations be executed as part of a transaction. 
Some transactions can cause side effects, such as the creation of new resources or other 
actions that may be difficult to fit into a transaction framework. Input regarding this 
issue is sought during the DSTU period.
</p>
<p>
Provide feedback <a href="http://wiki.hl7.org/index.php?title=FHIR_Specification_Feedback_(DSTU_2)">here</a>.
</p>
</blockquote>

<p>
A transaction may include references from one resource to another in the bundle, including
circular references where resources refer to each other. If the server assigns
a new id to any resource in the bundle as part of the processing rules above,
it SHALL also update any references to that resource in the same bundle as they
are processed. References to resources that are not
part of the bundle are left untouched. Version-specific references should remain
as version-specific references after the references have been updated.
Servers SHALL replace all matching links in the bundle, whether they are found in the resource ids,
resource references, url elements, or <code>&lt;a href="" &amp; &lt;img src=""</code> in the narrative.
</p>
<p>
When processing a batch or transaction, a server MAY choose to honor existing 
logical ids (e.g. <code>Observation/1234</code> remains as <code>Observation/1234</code> on the server), but 
since this is only <a href="#upsert">safe in controlled circumstances</a>, servers
may choose to assign new ids to all submitted resources, irrespective of any claimed
logical <code>id</code> in the resource, or <code>fullUrl</code> on entries in the batch/transaction.
</p>

<a name="transaction-response"> </a>
<h4>Batch/Transaction Response</h4>

<p>
In order to allow the client to know the outcomes of processing the entry, and the identities
assigned to the resources by the server, the server SHALL return a <a href="compartments.html#bundle">Bundle</a> with
<a href="bundle-definitions.html#Bundle.type">type</a> set to <code>batch-response</code> or <code>transaction-response</code> that contains one entry for each entry in the
request, in the same order, with the outcome of processing the entry.
</p>

<p>
Each entry element SHALL contain a <code>response</code> element which
details the outcome of processing the entry - the HTTP status code, and the location
and <code>ETag</code> header values, which are used for identifying and versioning the resources.
In addition, a resource may be included in the entry, as specified by the <a href="#prefer">Prefer</a> header.
</p>

<a name="other-bundles"> </a>
<h4>Accepting Other bundle types</h4>

<p>
A server may choose to accept bundle types other than <code>batch</code> or <code>transaction</code> when <code>POST</code>ed to the [base] URL.
</p>
<p>
Bundles of type <code>history</code> inherently have the same structure as a <code>transaction</code>, and
can be treated as either a transaction or batch, so servers SHOULD accept a history bundle - this makes it
possible to replicate data from one server to another easily using a pub/sub model. Note, however, that
the original transaction boundaries may not represented in a history list, and
a resource may occur more than once in a history list, so
servers processing history bundles must have some strategy to manage this.
</p>
<p>
For other bundle types, should the server choose to accept them, there will be
no <code>request</code> element (note that every entry will have a resource).
In this case, the server treats the entry as either a create or an update interaction,
depending on whether it recognises the identity of the resource - if the identity
of the resource refers to a valid location on the server, it should treat it
as an update to that location. Note: this option allows a client to delegate
the matching process to the server.
</p>


<a name="history"> </a>
<h3>history</h3>
<p>
The history interaction retrieves the history of either a particular resource, all resources of
a given type, or all resources supported by the system. These three variations of the history
interaction are performed by HTTP <code>GET</code> command as shown:
</p>
<pre>
  GET [base]/[type]/[id]/_history{?[parameters]&amp;_format=[mime-type]}
  GET [base]/[type]/_history{?[parameters]&amp;_format=[mime-type]}
  GET [base]/_history{?[parameters]&amp;_format=[mime-type]}
</pre>
<p>
The return content is a <a href="compartments.html#bundle">Bundle</a> with
<a href="bundle-definitions.html#Bundle.type">type</a> set to <code>history</code> containing the 
specified version history, sorted with oldest versions last, and including deleted resources.
Each entry SHALL minimally contain either a <code>resource</code> which holds the resource as 
it is at the conclusion of the interaction, or a <code>request</code> with <code>entry.request.method</code> 
The <code>request</code> provides information about the interaction that occurred to 
cause the new version, and allows, for instance, subscriber system to differentiate between 
create and update interactions. The principal reason a <code>resource</code> might be missing 
is that the resource was changed by some other channel rather than via the RESTful interface. If 
the <code>entry.request.method</code> is a <code>PUT</code> or a <code>POST</code>, the entry 
SHALL contain a resource.
</p>
<p>
The interactions <a href="#create"><code>create</code></a>, <a href="#update"><code>update</code></a>, and <a href="#delete"><code>delete</code></a>
create history entries. Other interactions do not (note that these operations may produce side-effects
such as new AuditEvent resources; these are represented as create interactions in their own right).
New resources or updates to existing resources that are triggered by operations also appear in the 
history, as to updates to the resources that result from interactions outside the scope of the
RESTful interface.
</p>
<p>
A create interaction is represented in a history interaction in the following way:
</p>
<pre class="xml">
  &lt;entry&gt;
    &lt;resource&gt;
      &lt;Patient&gt;
        &lt;!-- the id of the created resource --&gt;
        &lt;id value=&quot;23424&quot;/&gt;
        &lt;!-- snip --&gt;
      &lt;/Patient&gt;
    &lt;/resource&gt;
    &lt;request&gt;
      &lt;!-- POST: this was a create --&gt;
      &lt;method value="POST"/&gt;
      &lt;url value="Patient"/&gt;
    &lt;/request&gt;
  &lt;/entry&gt;
</pre>
<p>
Note that conditional creates, updates and deletes are converted to direct
updates and deletes in a history list.
</p>
<p>
In addition to the standard <code>_format</code> parameter, the parameters to this interaction may also include:
</p>
<table class="list">
  <tr><td><code>_count</code> : <a href="datatypes.html#integer"><code>integer</code></a></td><td>single</td><td>Number of return records requested. The server is not bound to return the number requested, but cannot return more</td></tr>
  <tr><td><code>_since</code> : <a href="datatypes.html#integer"><code>instant</code></a></td><td>single</td><td>Only include resource versions that were created at or after the given instant in time</td></tr>
</table>
<p>
The history list can be restricted to a limited period by specifying a <code>_since</code> parameter which contains a full date time with time zone.
Clients should be aware that due to timing imprecision, they may receive notifications of a resource update on the boundary instant more than once. Servers are
not required to support a precision finer than by second.
</p>
<p>
The updates list can be long, so servers may use paging. If they do, they SHALL use the method <a href="#paging">described
below</a> for breaking the list into pages if appropriate, and maintain the specified _count across pages.
</p>
<p>
The history interaction can be used to set up a subscription from one system
to another, so that resources are synchronized between them. Refer to the <a href="subscription.html">Subscription resource</a>
for an alternate means of system synchronization.
</p>

<a name="transactional-integrity"> </a>
<h3>Transactional Integrity</h3>
<p>
When processing <a href="#create">create</a> and <a href="#update">update</a>
interactions, a FHIR server is not obliged to accept the entire resource as it
is; when the resource is retrieved through a <a href="#read">read</a> interaction
subsequently, the resource may be different. The difference may arise for
several reasons:
</p>
<ul>
 <li>The server merged updated content with existing content</li>
 <li>The server applied business rules and altered the content</li>
 <li>The server does not fully support all the features or possible values of the resource</li>
</ul>
<p>
Note that there is no general purpose method to make merging with existing content or
altering the content by business rules safe or predictable - what is possible,
safe and/or required is highly context dependent. These kinds of behaviors may
be driven by security considerations. With regard to incomplete support, clients can consult the server's
base conformance statement profile references to determine which features or
values the server does not support.
</p>
<p>
To the degree that the server alters the resource for any of
the 3 reasons above, the FHIR server will create implementation
consequences for the eco-system that it is part of, which will
need to be managed (i.e. it will cost more). For this reason, servers 
SHOULD change the resource as little as possible, given the constraints 
of the system exposing the FHIR resource. However due to the variability 
that exists within healthcare, this specification allows that servers 
MAY alter the resource on create/update.
</p>
<p>
Similarly, to the degree that an implementation context makes special
rules about merging content or altering the content, that context will
become more expensive to maintain.
</p>
<p>
Although these rules are stated with regard to servers, a similar
concept applies to clients - to the degree that different client
systems interacting with the server do not support the same feature
set, the clients and/or the server will be forced to implement custom
logic to prevent information from being lost or corrupted.
</p>
<p>
Some of these problems can be mitigated by following a pattern
built on top of version-aware updates. In this pattern:
</p>
<ul>
 <li>The server provides a <a href="#read"><code>read</code></a> interaction for any resource it accepts <a href="#update"><code>update</code></a> interactions on</li>
 <li>Before updating, the client <a href="#read"><code>read</code>s</a> the latest version of the resource</li>
 <li>The client applies the changes it wants to the resource, leaving other information intact (note the <a href="extensibility.html#exchange">extension related rules</a> around this)</li>
 <li>The client writes the result back as an <a href="#update"><code>update</code></a> interaction, and is able to handle a <code>409</code> or <code>412</code> response (usually by trying again)</li>
</ul>
<p>
If clients follow this pattern, then information from other systems
that they do not understand will be maintained through the update.
</p>
<p>
Note that it's possible for a server to choose to maintain the
information that would be lost, but there is no defined way for
a server to determine whether the client omitted the information
because it wasn't supported (perhaps in this case) or whether it
wishes to delete the information.
</p>
<h4>Conformance</h4>
<p>
Both client and server systems SHOULD clearly document how transaction
integrity is handled.
</p>
<blockquote class="dstu-note">
<a name="dstu-3"> </a>
<p>
<b>DSTU Note:</b>  For now, the only way to document how transaction integrity
is handled is as text in the narrative portions of the <a href="conformance.html">Conformance</a>
resource. Feedback during the Trial use period on what - if any - of this information
should be computable is welcome.
</p>
<p>
Provide feedback <a href="http://wiki.hl7.org/index.php?title=FHIR_Specification_Feedback_(DSTU_2)">here</a>.
</p>
</blockquote>



<a name="paging"> </a>
<h3>Paging</h3>
<p>
If servers provide paging for the results of a <a href="#search">search</a> or <a href="#history">history</a> interaction,
they SHALL conform to this method (adapted from <a href="https://tools.ietf.org/html/rfc5005">RFC 5005 (Feed
Paging and Archiving)</a> for sending continuation links to the client when returning a <a href="bundle.html">Bundle</a>
(e.g. with <code>history</code> and <code>search</code>). If the server does not do this then there is no way to continue paging.
</p>
<p>
This example shows the third page of a search result:
</p>

<pre class="xml">
&lt;Bundle xmlns="http://hl7.org/fhir"&gt;
  &lt;!-- snip metadata --&gt;
  &lt;!-- This Search. url starts with base search, and adds the effective
    parameters, and additional parameters for search state. All searches
    SHALL return this value.

	  In this case, the search continuation method is that the server
    maintains a state, with page references into the stateful list.
	--&gt;
  &lt;link&gt;
    &lt;relation value=&quot;self&quot;&gt;
    &lt;url value=&quot;http://example.org/Patient?name=peter&amp;stateid=23&amp;page=3&quot;/&gt;
  &lt;/link&gt;
  &lt;!-- 4 links for navigation in the search. All of these are optional, but recommended --&gt;

  &lt;link&gt;
    &lt;relation value=&quot;first&quot;/&gt;
    &lt;url value=&quot;http://example.org/Patient?name=peter&amp;stateid=23&amp;page=1&quot;/&gt;
  &lt;/link&gt;
  &lt;link&gt;
    &lt;relation value=&quot;previous&quot;/&gt;
    &lt;url value=&quot;http://example.org/Patient?name=peter&amp;stateid=23&amp;page=2&quot;/&gt;
  &lt;/link&gt;
  &lt;link&gt;
    &lt;relation value=&quot;next&quot;/&gt;
    &lt;url value=&quot;http://example.org/Patient?name=peter&amp;stateid=23&amp;page=4&quot;/&gt;
  &lt;/link&gt;
  &lt;link&gt;
    &lt;relation value=&quot;last&quot;/&gt;
    &lt;url value=&quot;http://example.org/Patient?name=peter&amp;stateid=23&amp;page=26&quot;/&gt;
  &lt;/link&gt;

  &lt;!-- then the search results... --&gt;
&lt;/Bundle&gt;
</pre>

<p>
The server need not use a stateful paging method as shown in this example - it is at
the discretion of the server how to best ensure that the continuation retains
integrity in the context of ongoing changes to the resources. An alternative approach
is to use version specific references to the records on the boundaries, but this is
subject to continuity failures when records are updated.
</p>
<p>
A server MAY inform the client of the total number of resources returned by the interaction for which the results are paged
using  the <a href="bundle-definitions.html#Bundle.total">Bundle.total</a>.
</p>
<p>Note that for search, where _include can be used to return additional related resources, the total number
of resources in the feed may exceed the number indicated in totalResults.</p>

<h3>Intermediaries</h3>
<p>
The HTTP protocol may be routed through an HTTP proxy such as
squid. Such proxies are transparent to the applications, though
implementers should be alert to the effects of caching, particularly
including the risk of receiving stale content. See the <a href="http://tools.ietf.org/html/rfc2616#page-74">HTTP specification</a>
for further detail
</p>
<p>
Interface engines may also be placed between the consumer and
the provider. These differ from proxies because they actively
alter the content and/or destination of the HTTP exchange and are
not bound the rules that apply to HTTP proxies. Such agents are allowed,
but SHALL mark the HTTP header to assist with troubleshooting.
</p>
<p>
Any agent that modifies an HTTP request or response content other
than under the rules for HTTP proxies SHALL add a stamp to the HTTP
headers like this:
</p>
<pre>
  request-modified-[identity]: [purpose]
  response-modified-[identity]: [purpose]
</pre>
<p>
The identity SHALL be a single token defined by the administrator of the agent
that will sufficiently identify the agent in the context of use. The header
SHALL specify the agent's purpose in modifying the content. End point systems SHALL
not use this header for any purpose. Its aim is to assist with
system troubleshooting.
</p>

<a name="hdata"> </a>
<h3>OMG hData RESTful Transport</h3>

<p>
This RESTful specification described here is based on the <a href="http://www.omg.org/spec/HData/">OMG Health RESTful specification (HData)</a>.
In this regard, FHIR functions as a Record Format Profile as described in that specification. Note the following significant factors to be aware of:
</p>
<ul>
 <li>FHIR maps the hData sections to resource types, and hData documents to resource instances. There are no subsections, and client systems are not able to create new sections,
 though <a href="compartments.html#compartments">compartments</a> behave somewhat like sections</li>
 <li>Because clients cannot submit new sections (<code>POST</code> to service URL), <code>POST</code> to the service URL has been re-used for <a href="#transaction">the transaction
 interaction</a> (difference under review)</li>
 <li>FHIR does not (yet) define a root document. When defined, it will contain information about what the FHIR server has done (as opposed to a conformance statement, which describes what it is capable of doing)</li>
 <li>Note that this specification does not repeat the rules in the hData RESTful Transport concerning the <code>OPTIONS</code> command on the service URL, but these rules (extra headers etc.) still apply</li>
</ul>

<a name="summary"> </a>
<h3>Summary</h3>
<p>
These tables present a summary of the interactions described here.

Note that <i>all</i> requests may include an optional <code>Accept</code> header to indicate the format used for the response (this is even true for <code>DELETE</code> since an OperationOutcome may be returned).
</p>

<table class="grid">
<tr><th>Interaction</th>                <th>Path</th><th colspan="5">Request</th></tr>
<tr><th colspan="2"></th>                                                       <th>Verb</th>           <th>Content-Type</th>   <th>Body</th>     <th>Prefer</th>         <th>Conditional</th></tr>
<tr><td><code>read</code></td>                       <td><code>/[type]/[id]</code></td>                   <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>      <td>N/A</td>     		  <td>O: <code>ETag</code>, <code>If-Modified-Since</code>, <code>If-None-Match</code></td></tr>
<tr><td><code>vread</code></td>                      <td><code>/[type]/[id]/_history/[vid]</code></td>    <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>      <td>N/A</td>         	<td>N/A</td></tr>
<tr><td><code>update</code></td>                     <td><code>/[type]/[id]</code></td>                   <td><code>PUT</code></td>            <td>R</td>              <td>Resource</td> <td>O</td>         	<td>O: <code>If-Match</code></td></tr>
<tr><td><code>delete</code></td>                     <td><code>/[type]/[id]</code></td>                   <td><code>DELETE</code></td>         <td>N/A</td>            <td>N/A</td>      <td>N/A</td>	         <td>N/A</td></tr>
<tr><td><code>create</code></td>                     <td><code><code>/[type]</code></code></td>                        <td>POST</td>           <td>R</td>              <td>Resource</td> <td>O</td>         <td>O: <code>If-None-Exist</code></td></tr>
<tr><td rowspan="2"><code>search</code></td>         <td><code>/[type]?</code></td>                       <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>	  <td>N/A</td>			<td>N/A</td></tr>
<tr>                                    <td><code>/[type]/_search?</code></td>               <td><code>POST</code></td>           <td><code>application/x-www-form-urlencoded</code></td>         <td>form data</td> <td>N/A</td>  <td>N/A</td></tr>
<tr><td rowspan="2"><code>search-all</code></td>     <td><code>/_search?</code></td>                      <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>              <td>N/A</td>  <td>N/A</td></tr>
<tr><td><code>conformance</code></td>                <td><code>/</code> or <code>/metadata</code></td>                 <td><code>OPTIONS</code> or <code>GET</code></td>  <td>N/A</td>           <td>N/A</td>	   <td>N/A</td>			   	<td>N/A</td></tr>
<tr><td><code>transaction</code></td>                <td><code>/</code></td>                              <td><code>POST</code></td>           <td>R</td>              <td><code>Bundle</code></td>    <td>O</td>        <td>N/A</td></tr>
<tr><td><code>history</code></td>                    <td><code>/[type]/[id]/_history</code></td>          <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>       <td>N/A</td>         <td>N/A</td></tr>
<tr><td><code>history-type</code></td>               <td><code>/[type]/_history</code></td>               <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>       <td>N/A</td>         <td>N/A</td></tr>
<tr><td><code>history-all</code></td>                <td><code>/_history</code></td>                      <td><code>GET</code></td>            <td>N/A</td>            <td>N/A</td>       <td>N/A</td>         <td>N/A</td></tr>
<tr><td rowspan="3">(operation)</td>    <td rowspan="3"><code>/$[name]</code>, <code>/[type]/$[name]</code>
										or <code>/[type]/[id]/$[name]</code></td> 		  	<td><code>POST</code></td>           <td>R</td>         		<td>Parameters</td><td>N/A</td>			<td>N/A</td></tr>
																		<tr>    <td><code>GET</code></td>           	<td>N/A</td>         	<td>N/A</td> 	   <td>N/A</td>  		<td>N/A</td></tr>
																		<tr>    <td><code>POST</code></td>          	<td><code>application/x-www-form-urlencoded</code></td>         	<td>form data</td> 	   <td>N/A</td>  		<td>N/A</td></tr>
</table>

<p>
Notes: 
</p>
<ul>
 <li>N/A = not present, R = Required, O = optional</li>
 <li>For operations defined on all resources, including direct access to the meta element, see <a href="resource-operations.html">Resource Operations</a></li>
</ul>

<table class="grid">
<tr><th>Interaction</th><th colspan="6">Response</th></tr>
<tr><th colspan="1"></th>   <th>Content-Type</th> <th>Body</th>               <th>Location</th> 	    <th>Versioning</th> 					<th>Status Codes</th></tr>
<tr><td><code>read</code></td>           <td>R</td>            <td>R: Resource</td>           <td>N/A</td>         <td>R: <code>ETag</code>, <code>Last-Modified</code></td>		<td><code>200</code>, <code>404</code>, <code>410</code></td></tr>
<tr><td><code>vread</code></td>          <td>R</td>            <td>R: Resource</td>           <td>N/A</td>         <td>R: <code>ETag</code>, <code>Last-Modified</code></td>		<td><code>200</code>, <code>404</code></td></tr>
<tr><td><code>update</code></td>         <td>R if body</td>    <td>O: Resource (Prefer)</td>  <td>R on create</td>	<td>R: <code>ETag</code>, <code>Last-Modified</code></td>		<td><code>200</code>, <code>201</code>, <code>400</code>, <code>404</code>, <code>405</code>, <code>409</code>, <code>412</code>, <code>422</code></td></tr>
<tr><td><code>delete</code></td>         <td>R if body</td><td>O: OperationOutcome</td>  <td>N/A</td>      	      <td>N/A</td>							<td><code>200</code>, <code>204</code>, <code>404</code>, <code>405</code>, <code>409</code>, <code>412</code></td></tr>
<tr><td><code>create</code></td>         <td>R if body</td>    <td>O : Resource (Prefer)</td>  <td>R</td>			    <td>R: <code>ETag</code>, <code>Last-Modified</code></td>		<td><code>201</code>, <code>400</code>, <code>404</code>, <code>405</code>, <code>422</code></td></tr>
<tr><td><code>search</code></td>         <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code>, <code>403</code>?</td></tr>
<tr><td><code>search-all</code></td>     <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code>, <code>403</code>?</td></tr>
<tr><td><code>conformance</code></td>    <td>R</td>            <td>R: Conformance</td>        <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code>, <code>404</code></td></tr>
<tr><td><code>transaction</code></td>    <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code>, <code>400</code>, <code>404</code>, <code>405</code>, <code>409</code>, <code>412</code>, <code>422</code></td></tr>
<tr><td><code>history</code></td>        <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>     		<td>N/A</td>							<td><code>200</code></td></tr>
<tr><td><code>history-type</code></td>   <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code></td></tr>
<tr><td><code>history-all</code></td>    <td>R</td>            <td>R: Bundle</td>             <td>N/A</td>      	  <td>N/A</td>							<td><code>200</code></td></tr>
<tr><td>(operation)</td>   	<td>R</td> 			      <td>R: Parameters/Resource</td><td>N/A</td>    	    <td>N/A</td>			        <td><code>200</code></td></tr>
</table>

<p>
Note: this table lists the status codes described here, but other status codes are possible as described by the HTTP specification.
Additional codes that are likely are server errors and various codes associated with authentication protocols.
</p>

</div>

[%onthispage Interactions#interactions|Paging#paging|hData Information#hdata|Summary#summary%]

[%file newfooter%]
</body>
</html>


