This page is part of the FHIR Specification (v0.0.82: (v1.0.2: DSTU 1). 2). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

2.1 2.1.0 RESTful API

FHIR Infrastructure Work Group

Maturity Level : N/A

Ballot Status : DSTU 2

Each resource type "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". FHIR" (see Conformance ).

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 Security Page .

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 conformance statement that specifies what which interactions and resources are supported.

The following logical interactions are defined:

validate Check that the content would be acceptable as an update

Instance Level Interactions
read	Read the current state of the resource
vread	Read the state of a specific version of the resource
update	Update an existing resource by its id (or create it if it is new)
delete	Delete a resource
history	Retrieve the update history for a particular resource
Type Level Interactions
create	Create a new resource with a server assigned id
search	Search the resource type based on some filter criteria
history	Retrieve the update history for a particular resource type
Whole System Interactions
conformance	Get a conformance statement for the system
transaction batch/transaction	Update, create or delete a set of resources as in a single transaction interaction
history	Retrieve the update history for all resources
search	Search across all resource types based on some filter criteria

In addition to these operations, interactions, there is a an operations framework , which includes endpoints for validation , Mailbox messaging and Document endpoint. Documents .

Style Guide

URL operations The interactions on this pages page are defined like this:

  OPERATION [base]/[type]/[id] {?_format=[mime-type]}

  VERB [base]/[type]/[id] {?_format=[mime-type]}

• The first word is the HTTP verb used for the operation interaction
• Content surrounded by [] is mandatory, and will be replaced by the string literal identified. Possible insertion values:
  • base : : The Service Root URL
  • mime-type : : The Mime Type
  • type : : The name of a resource type (e.g. "Patient")
  • id : : The Logical Id of a resource
  • vid : : The Version Id of a resource
  • compartment : : The name of a compartment
  • parameters : : URL parameters as defined for the particular operation interaction
• Content surrounded by {} is optional

Implementations constructing URLs using these patterns SHOULD conform to RFC 3986 Section 6 Appendix A which requires percent-encoding for a number of characters that occasionally appear in the URLs (mainly in search parameters).

This specification uses the underscore as a prefix to disambiguate reserved names from other names in 3 cases:

• To differentiate system wide history and search interactions from interactions on Resource Types
• To differentiate search, history and similar interactions from instances of a resource type
• To differentiate search parameters defined for all resources from those defined for specific resource types

In addition, the character $ 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.

2.1.1 2.1.0.1 Service Root URL

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

http(s)://server{/path}

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 "/[type]" /[type] where the "type" [type] is the name of the resource type. For instance, the resource manager for the type "Patient" Patient will live at:

https://server/path/Patient

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.

Note: All URLs (and ids that form part of the URL) defined by this specification are case sensitive.

Note that a server may use a path of the form "http://server/...[xx]..." http://server/...[xx]... where the [xx] 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 [xx]. [xx] . 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 - see implementations can associate an FHIR end-point with a particular patient or provider by using an OAuth login. See Compartments for an alternative approach. the logical underpinning.

Identity

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:

• The query part of the URL (anything after ? ) is ignored
• The comparison of the document portion of the URL (i.e. not the server/port) is case sensitive
• The protocols http: and https: SHALL NOT be used to refer to different underlying objects
• 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

For example: http://myserver.com/patient/1 and https://myserver.com/patient/1 refer to the same underlying object, while http://myserver.com:81/patient/1 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.

2.1.2 2.1.0.2 Resource Metadata and Versioning

Each resource has an associated set of resource metadata elements . These map to the http HTTP request and response using the following fields:

Metadata Item	Where found in HTTP
Logical Id (.id)	The Id is represented explicitly in the URL
Version Id (.meta.versionId)	The Version Id is represented by the full canonical URL in the content-location header (see vread below). The Version Id may also be represented in the http ETag, but the use of ETag is not needed by this specification header
Last Modified Date modified (.meta.lastUpdated)	HTTP Last-Modified header

Note that the Version Id is considered a "weak" ETag and ETag headers should be prefixed with W/ and enclosed in quotes, for example:

ETag: W/"3141"

2.1.3 2.1.0.3 Security

Using HTTPS is optional, but all production exchange of healthcare data SHOULD use SSL and additional security as appropriate. See HTTP Security for further information. Most operations will require user authentication, and all operations that do are subject to RBAC and/or ABAC , and some operations may depend on appropriate consent being granted.

The choice of whether to return 403 Unauthorised or 404 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 404 does not leak information, it should be the default choice unless there is a specific reason to return a 403 .

Note: to support browser-based client applications, recommend that servers SHOULD implement cross-origin resource sharing for the operations 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.

2.1.4 2.1.0.4 HTTP Status Codes

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).

FHIR defines an OperationOutcome resource 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 4xx or 5xx response, but is not required - many of these errors may be generated by generic server frameworks underlying a FHIR server.

2.1.5 2.1.0.5 Managing Return Content

In the interests of managing band-width, this specification allows clients to specify what kind of content to return.

2.1.0.5.1 conditional read

Clients may use the If-Modified-Since , or If-None-Match HTTP header on a read request. If so, they MUST accept either a 304 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).

Servers can return 304 Not Modified where content is unchanged since the If-Modified-Since date-time or the If-None-Match 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.

2.1.0.5.2 create/update/transaction

These interactions are performed using POST , PUT and POST 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 Bundle.entry.response populated for each entry, and not the Bundle.entry.resource values.

The client can indicate whether the entire resource is returned using the HTTP return preference :

Prefer: return=minimal
Prefer: return=representation

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 successful interactions. In case of failure, servers SHOULD always return a body that contains an OperationOutcome resource.

2.1.0.6 Content Types and encodings

The formal MIME-type for FHIR resources is application/xml+fhir or application/json+fhir. application/json+fhir . The correct mime type SHALL be used by clients and servers:

xml json Resource application/xml+fhir application/json+fhir Bundle application/atom+xml application/json+fhir TagList

• XML: application/xml+fhir
• JSON: application/json+fhir

Servers SHALL support server-driven content negotiation as described in section 12 of the HTTP specification.

However in order to support various implementation limitations, servers SHOULD support the optional "_format" _format parameter to specify alternative response formats by their MIME-types. This parameter allows a client to override the accept header value when it is unable to set it correctly due to internal limitations. limitations (e.g. XSLT usage). For the _format parameter, the values "xml", "text/xml", "application/xml", xml , text/xml , application/xml , and "application/xml+fhir" application/xml+fhir SHALL be interpreted to mean the normative XML format defined by FHIR and "json", "application/json" json , application/json and "application/json+fhir" application/json+fhir SHALL be interpreted to mean the informative JSON format. In addition, the values html and text/html are allowed.

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 'charset' charset parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.

Note: the _format parameter does not override the content-type header.

The content types application/x-www-form-urlencoded is also accepted for posting search requests.

2.1.6 2.1.0.7 Support for Versions

Servers that support this API SHOULD provide full version support - that is, populate and track versionId correctly, support vread , and implement version aware updates . 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.

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 conformance statement .

Server should always return the default timezone for date searches in the HTTP Response headers using the Date header. Note: Servers are not required to have a default timezone.

2.1.0.8 read

The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET command as shown:

  GET [base]/[type]/[id] {?_format=[mime-type]}

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 Logical Id (id) ("id") itself are described in the id type . The returned resource SHALL have an id element with a value that is the [id]. Servers are required to SHOULD return a content-location an ETag header with the response which is versionId of the full version specific url (see vread below) resource (if versioning is supported) and a Last-Modified header.

Note: Unknown resources and deleted resources are treated differently on a read: A GET for a deleted resource returns a 410 status code, whereas a GET for an unknown resource returns 404. 404 . 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.

In addition, the search parameter _summary can be used when reading a resource:

  GET [base]/[type]/[id] {?_summary=text}

This requests that only a subset of the resource content be returned, as specified in the _summary parameter, which can have the values true , false , text & data . 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 SUBSETTED Security Label to explicitly mark such resources.

2.1.7 2.1.0.9 vread

The vread interaction preforms a version specific read of the resource. The interaction is performed by an HTTP GET command as shown:

  GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}

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 id element with a value that is the [id] , and a meta.versionId element with a value of [vid] . Servers SHOULD return an ETag header with the versionId (if versioning is supported) and a Last-Modified header.

The Version Id (vid) ("vid") is an opaque identifier that conforms to the same format requirements as a Logical Id . 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 read 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 410 status code.

Servers are encouraged to support a version specific retrieval of the current version of the resource even if they are 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 405 Method 404 Not Allowed error. Found error, with an operation outcome explaining that history is not supported for the underlying resource type.

2.1.8 2.1.0.10 update

The update interaction creates a new current version for an existing resource or creates a new resource an initial version if no resource already exists for the given id. The update interaction is performed by an HTTP PUT command as shown:

  PUT [base]/[type]/[id] {?_format=[mime-type]}

The request body SHALL be a Resource with an id element that has an identical value to the [id] in the URL. If no id element is provided, or the interaction value is successful, wrong, the server SHALL return either a 200 OK if the resource was updated, or a 201 Created if the resource was created, respond with a Last-Modified header, and a Location HTTP 400 error code, and Content-Location header that refers to SHOULD provide an operation outcome identifying the specific version created by issue. If the request body includes a meta , the update interaction. The server MAY send an OperationOutcome resource with hints SHALL ignore the existing versionId and warnings about lastUpdated values. If the resource; if one is sent server supports versions, it SHALL not include any errors. populate the meta.versionId and meta.lastUpdated with the new correct values. Servers are permitted allowed to reject update interactions because of integrity concerns or business rules implemented on the server, review and return HTTP status codes accordingly (usually 422). alter the other metadata values, but SHOULD refrain from doing so (see metadata description for further information).

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 transactional integrity for discussion. Also, see Variations between Submitted data and Retrieved data for additional discussion around update behavior.

In particular, servers may choose to implement version-aware updates, where the only DSTU Note: The update operation updates that are accepted quote the current version of the entire resource. In Servers MAY apply some logic and preserve some existing content based where this case, the client must submit the currently correct version specific URL in the Content-Location in the PUT request. is known to be appropriate behavior. HTTP PATCH functionality is likely to be defined, and feedback from outcomes of implementer experimentation is welcome.

Provide feedback here .

If the value interaction is missing, successful, the server SHALL return either a 412 Preconditions failed response. Clients 200 OK HTTP status code if the resource was updated, or a 201 Created status code if the resource was created, with a Last-Modified header, and an ETag header which contains the new versionId of the resource. If the resource was created (i.e. the interaction resulted in a 201 Created), the server SHOULD submit return a proper Content-Location Location header (this is for HTTP conformance; it's not otherwise needed).

Note: Servers MAY choose to preserve XML comments, instructions, and SHALL correctly understand 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.

Note that servers MAY choose to allow clients to PUT a 409 response as 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:

• client is reproducing an existing data model on the server, and needs to keep original ids in order to retain ongoing integrity
• client is a server doing push based pub/sub (this is a special case of the first reason)
• multiple clients doing push in the context of agreed data model shared across multiple servers where ids are shared across servers

Alternatively, clients may be sharing an agreed identification model (e.g. key server, scoped identifiers, or UUIDs) where clashes do not arise.

Servers can choose whether or not to support client defined ids, and indicate such to the clients using Conformance.rest.resource.updateCreate .

2.1.0.10.1 Rejecting Updates

Servers are permitted to reject update conflict. interactions because of integrity concerns or other business rules, and return HTTP status codes accordingly (usually a 422 ).

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

• 400 Bad Request - resource could not be parsed or failed basic FHIR validation rules (or multiple matches were found for
• 403 Not Authorized - authorization is required for the interaction that was attempted
• 404 Not Found - resource type not supported, or not a FHIR end point end-point
• 405 Method Not allowed - the resource did not exist prior to the update, and the serer server does not allow client defined ids
• 409/412 409 / 412 - version conflict management - see above below
• 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules. This should rules

Any of these errors SHOULD be accompanied by an OperationOutcome resource providing additional detail concerning the issue.

Note: Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace For additional information on how systems may behave when accepting processing updates, but are not required refer to do so. the Variations between Submitted data and Retrieved data page.

2.1.0.10.2 Conditional update

The impact conditional update interaction allows a client to update an existing resource based on some identification criteria, rather than by logical id . To accomplish this, the client issues a PUT as shown:

  PUT [base]/[type]/?[search parameters]

When the server processes this update, it performs a search using its standard search facilities for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends on digital signatures may need to how many matches are found:

• No matches : The server performs a create interaction
• One Match : The server performs the update against the matching resource
• Multiple matches : The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough

This variant can be considered. 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 PUT /Observation?identifier=http://my-lab-system|123

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 400 error and an operation outcome.

2.1.9 2.1.0.11 Managing Resource Contention

Lost Updates , where two clients update the same resource, and the second overwrites the updates of the first, can be prevented using a combination of the ETag and If-Match header.

To support this usage, servers SHOULD always return an ETag header with each resource:

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

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 id 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.

If the client wishes to request a version aware update, it submits the request with an If-Match header that quotes the ETag from the server:

PUT /Patient/347 HTTP/1.1
If-Match: W/"23"

If the version id given in the If-Match header does not match, the server returns a 409 Conflict status code instead of updating the resource.

Servers can require that clients provide an If-Match header by returning 412 Pre-condition failed status codes when no If-Match header is found.

2.1.0.12 delete

The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE command as shown:

  DELETE [base]/[type]/[id] 

  DELETE [base]/[type]/[id]

A delete interaction means that subsequent non-version specific reads of a resource return a 410 error HTTP status code and that the resource is no longer found through search interactions. Upon successful deletion deletion, or if the resource does not exist at all, the server should return 204 (No Content). The server MAY send an OperationOutcome resource with hints and warnings about the deletion; if one is sent it SHALL not include any errors. No Content .

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 on principle, as a blanket policy, then it should return the status code 405 method Method not allowed. 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 status code 409 Conflict. If the resource cannot be deleted because it does not exist on the server, the server SHALL return 404 (Not found). Conflict status code. Performing this interaction on a resource that is already deleted has no effect, and the server should return 204. a 204 or 200 response. Resources that have been deleted may subsequently be brought "brought back to life life" by PUTting an update to them a subsequent to the deletion. update interaction using an HTTP PUT .

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.

For servers that maintain a version history, the delete 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.

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.

2.1.0.12.1 Conditional delete

The conditional delete interaction allows a client to delete an existing resource based on some selection criteria, rather than by a specific logical id . To accomplish this, the client issues an HTTP DELETE as shown:

  DELETE [base]/[type]/?[search parameters]

When the server processes this delete, it performs a search as specified using the standard search facilities for the resource type. The action it takes depends on how many matches are found:

• No matches : The server returns 404 Not found
• One Match : The server performs an ordinary delete on the matching resource
• Multiple matches : Servers may choose to delete all the matching resources, or it may choose to return a 412 Precondition Failed error indicating the client's criteria were not selective enough. A server indicates whether it can delete multiple resources in its Conformance Statement (.rest.resource.conditionalDelete) . if there are multiple matches, either all must deleted, or the server SHALL return an error

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 DELETE /Observation?identifier=http://my-lab-system|123 .

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 400 error and an operation outcome.

2.1.10 2.1.0.13 create

The create interaction creates a new resource in a server assigned server-assigned location. If the client wishes to have control over the id of a newly submitted resource, it should use the update interaction instead. The create interaction is performed by an HTTP POST command as shown:

  POST [base]/[type] {?_format=[mime-type]}

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 400 error code, and SHOULD provide an operation outcome identifying the issue. If the request body includes a meta , the server SHALL ignore the existing versionId and lastUpdated values. The server SHALL populate the meta.versionId and meta.lastUpdated with the new correct values. Servers are allowed to review and alter the other metadata values, but SHOULD refrain from doing so (see metadata description for further information).

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 transactional integrity for discussion.

The server returns a 201 Created, along with Created HTTP status code, and SHOULD also return a Location header which contains the new Logical Id and Version Id of the created resource: resource version:

  Location: [base]/[type]/[id]/_history/[vid]

Where where [id] and [vid] are the newly created id and version id for the resource. The server MAY send an OperationOutcome resource version. Servers SHOULD return an ETag header with hints and warnings about the resource; if one versionId (if versioning is sent it SHALL not include any errors. supported) and a Last-Modified header.

When the payload resource syntax or data is incorrect or invalid, and cannot be used to create a new resource, the server returns a 400 Bad Request. A Request HTTP status code. When the server SHOULD accept rejects the resource as submitted when accepts content of the create, and return resource because of business rules, the same content when it is subsequently read. However systems may not be able to do this; see server returns a 422 Unprocessible Entity error HTTP status code. In either case, the note on transactional integrity server SHOULD include a response body containing an OperationOutcome with detailed error messages describing the reason for discussion. the error.

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

• 400 Bad Request - resource could not be parsed or failed basic FHIR validation rules
• 404 Not Found - resource type not supported, or not a FHIR end point end-point
• 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an OperationOutcome resource providing additional detail

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.

For additional information on how systems may behave when processing updates, refer to the Variations between Submitted data and Retrieved data page.

2.1.11 2.1.0.13.1 Conditional create

The conditional create 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 If-None-Exist header as shown:

  If-None-Exist: [search parameters]

The parameter just contains the search parameters (what would be in the URL following the "?").

When the server processes this create, it performs a search as specified using its standard search facilities for the resource type. The action it takes depends on how many matches are found:

• No matches : The server processes the create as above
• One Match : The server ignore the post and returns 200 OK
• Multiple matches : The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough

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 If-None-Exist: identifier=http://my-lab-system|123 to ensure it is does not create a duplicate record.

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 412 error and an operation outcome.

2.1.0.14 search

This interaction searches a set of resources based on some filter criteria. The interaction can be performed by several different HTTP commands. To search all resources at once:

  GET [base]?[parameters] {&_format=[mime-type]}
To
search
a
single
resource
type:

  GET [base]/[type]?[parameters] {&_format=[mime-type]}
  GET [base]/[type]/_search?[parameters] {&_format=[mime-type]}

  GET [base]/[type]{?[parameters]{&_format=[mime-type]}}

To search This searches all resources of a compartment : particular type using the criteria represented in the parameters.

GET [base]/[compartment]/[id]/?[parameters] {&_format=[mime-type]} GET [base]/[compartment]/[id]/[type]?[parameters] {&_format=[mime-type]}

Because of the way that some user agents and proxies treat GET and POST requests, POST submissions in addition to /_search are the get based search method above, servers that support search SHALL also allowed with support a POST based search:

POST  [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}

This has exactly the same semantics as the equivalent GET command. All these search interactions take a series of parameters that are a series of name'='value name=value pairs encoded in the URL (or as an x-multi-part-form application/x-www-form-urlencoded submission for a POST). POST ). (See W3C HTML forms ).

Note: application/x-www-form-urlencoded is supported for POST so that invoking a search by GET or POST 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.

Searches are processed as specified for the Search/Query Search handling mechanism .

If the search fails, fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx with an OperationOutcome . If the search succeeds, the return content is an a Bundle with type = searchset 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 described in below (adapted from RFC 5005 (Feed Paging and Archiving) (also see below Archiving ) 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 NOT include any errors. errors, and it shall be marked with an entry mode of include .

2.1.12 2.1.0.14.1 validate Variant Searches

The validate interaction checks whether the attached content would be acceptable as an update to an existing resource. The interaction is performed by an HTTP POST command as shown: To search a compartment , for either all possible resources or for a particular resource type, respectively:

  POST [base]/[type]/_validate{/[id]}

  GET [base]/[Compartment]/[id]/{*?[parameters]{&_format=[mime-type]}}
  GET [base]/[Compartment]/[id]/[type]{?[parameters]{&_format=[mime-type]}}

The content is first checked against the general specification and against the conformance profile that applies For example, to retrieve all the application. Then, if the optional [id] section is also provided, the resource is considered as observation resources for a proposed update to the specific resource, and additional instance specific rules such as referential integrity and update logic (including version control) are applied as well. particular LOINC code associated with a particular encounter:

  GET [base]/Encounter/23423445/Observation?code=2951-2  {&_format=[mime-type]}

The client can ask the server Note that there are specific operations defined to validate against a particular resource by attaching a profile tag support fetching an entire patient record to the resource. This is or all record for an assertion that the resource conforms to the specified profile(s), and the server can check this. encounter .

How much checking to perform as part of the validation operation is at the discretion of the server. The server SHALL check all the things it requires of the resource as part of Finally, it's normal operations, and MAY choose possible to validate the resource against the schema and schematron provided as part of this specification, and/or other profiles, including the one specified by the client. search all resources at once:

  GET [base]?[parameters]{&_format=[mime-type]}

The return content has one of the following values: 400 Bad Request - resource could not be parsed or had some basic FHIR validation error 200 OK - resource passed When searching all validation rules 422 Unprocessable Entity - the resource was valid, but as a proposed update, it violates applicable FHIR profiles or server business rules Unless the result is 200 OK, resources at once, only the response SHALL include an OperationOutcome parameters defined for all resources resource that lists the issues found on validation. can be used.

2.1.13 2.1.0.15 conformance

The conformance interaction retrieves the server's conformance statement that defines how it supports resources. The interaction is performed by an HTTP OPTIONS or a GET command as shown:

  GET [base]/metadata {?_format=[mime-type]}
  OPTIONS [base] {?_format=[mime-type]}

Applications SHALL return a Conformance Resource that specifies which resource types and interactions are supported for the GET command, and SHOULD do so for the OPTIONS command. If a 404 Unknown is returned from the GET, GET , FHIR is not supported on the nominated service url. The GET command is defined because not all client libraries are able to perform an OPTIONS command. A Content-Location An ETag header SHALL SHOULD be returned with the conformance resource. The value of the header SHALL change if the conformance statement itself changes. The URI provided in the header MAY be a literal location where this version of the conformance statement is (and will continue to be) available. Additional parameters that are required to be returned with the OPTIONS command are defined in the OMG hData RESTful Transport specification.

The Conformance statement returned typically has an arbitrary id, and no meta element, though it is not prohibited.

In addition to this conformance operation, interaction, a server may also choose to provide the standard set of interactions (read, search, create, update) ( read , search , create , update ) defined on this page for the Conformance Resource end-point. This is different to from the conformance operation: interaction:

conformance operation interaction	returns a conformance statement describes describing the server's current operational functionality
Conformance conformance end-point	manages a repository of conformance statements (e.g. the HL7 conformance statement registry)

All servers are required to support the conformance operation, interaction, but servers may choose whether they wish to support the conformance end-point, just like any other end-point.

2.1.14 2.1.0.16 transaction batch/transaction

The batch and transaction interaction submits interactions submit a set of resources actions to be updated, created or deleted perform on the server. This interaction allows multiple resources to be updated/created a server in a single transaction on HTTP request/response. The actions may be performed independently as a "batch", or as a single server. 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 new and existing resources. other interactions defined on this page (e.g. read , search , create , update , delete , etc.), or using the operations framework.

This The transaction mode is especially useful where one would otherwise need multiple interactions, possibly leading to 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), resource, or, on document repositories, a document index entry and its accompanying document. document).

The Note that transactions and conditional create/update/delete are complex interactions and it is not expected that every server will implement them.

A batch or transaction interaction is performed by an HTTP POST command as shown:

  POST [base] {?_format=[mime-type]}

The content of the post submission is a Bundle with Bundle.type = batch or transaction . Each entry carries request details ( Bundle.entry.request ) 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 (note: the request is optional , but SHOULD be present). If the HTTP command is a PUT or POST , then the entry SHALL contain a resource bundle. for the body of the action. The resources in the bundle are each processed separately as if they were an individual create , update interactions or operations as otherwise described on this page, or delete , along with the Operations framework . The actions are subject to the normal processing for each (such as tracking tags, each, including the meta element , verification and version aware updates, subject to the note on and transactional integrity .

Examples:

• Transaction ).
• Matching Response

2.1.0.16.1 Batch Processing Rules

For a batch , there SHALL be no interdependencies between the different entries in the Bundle. The success or failure of one entry SHALL not alter the success 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 execution should not matter given the previous rule.

2.1.0.16.2 Transaction Processing Rules

For a transaction , servers SHALL either accept all resources actions and return a 200 OK, along with a response bundle, bundle (see below), or reject all resources and return an HTTP 400 or 500 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 NOT depend on the order of the resources in the transaction. Note that this means that a A resource can only appear in a transaction once, and since bundles may have the same resource more than once or other order dependencies (e.g. update lists), some kinds of bundles may not be able to be used in a transaction. (by identity).

When a bundle is submitted in Because of the rules that a transaction interaction, is atomic where all actions pass or fail together and the resources have an identity specified order of the entries doesn't matter, there is a particular order in which to process the bundle. actions:

1. Process any DELETE interactions
2. Process any POST interactions
3. Process any PUT interactions
4. Process any GET interactions

If the identity of the resource matches an existing or possible any resource location on the server, identities (including resolved identities from conditional update/delete) overlap in steps 1-3, then the server should treat this entry as an update interaction transaction SHALL fail.

(i.e. PUT

DSTU Note: clients are able to the given resource). If the identity is not one request that the server recognizes operations be executed as part of a resource location it transaction. Some transactions can use, the server should treat the interaction cause side effects, such as a create interaction (i.e. POST to the given resource type URL), and create a creation of new identity for the submitted resource. Note resources or other actions that the client SHALL provide an identity in the bundle entry.id, but may also provide a version specific identity the atom "self" link, and may refer be difficult to fit into a transaction framework. Input regarding this for version specific references. Deleted resources are those marked using issue is sought during the method described for XML or JSON DSTU period.

Provide feedback here .

A transaction may include references from one resource to another in the bundle, which may include including circular references where resources refer to each other. If the server assigns a new identity id to any resource in the bundle, 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. If a resource in the bundle carries a version-specific id (using its self-link), any Version-specific references should remain as version-specific references to it SHALL also be after the references have been updated. Servers SHALL be replace all matching links in the bundle, whether they are found in the resource ids, resource references, url elements, or <a href="" & <img src="" in the narrative.

A client may assign temporary ids to new resources and then refer to them from other places in the transaction. When the client intends processing a resource to have batch or transaction, a transient identity that the server must replace, it should use a cid: url MAY choose to honor existing logical ids (e.g. Observation/1234 remains as Observation/1234 on the resource - that is, a url with the scheme "cid:" per RFC 2392 . Servers SHALL replace these temporary server), but since this is only safe in controlled circumstances , servers may choose to assign new ids when processing to all submitted resources, irrespective of any claimed logical id in the transaction. resource, or fullUrl on entries in the batch/transaction.

2.1.0.16.3 Batch/Transaction Response

In order to allow the client to know how newly created the outcomes of processing the entry, and the identities assigned to the resources are now identified for future reference, by the server, the server SHALL return a bundle Bundle with type set to batch-response or transaction-response that contains one entry for each resource in the transaction, with the following properties: The server assigned id in entry.id If vread is supported, the specific version reference entry in a "self" link on the entry The client assigned id request, in a "alternate" link on the entry entry.content and entry.summary are not required The server MAY also return an OperationOutcome resource same order, with additional information about the transaction; if one is sent it SHALL not include any errors if outcome of processing the transaction was successful. entry.

The application constructing a bundle may not be sure whether Each entry element SHALL contain a particular resource will already exist at response element which details the time that outcome of processing the transaction is executed; this is typically entry - the case with reference resources such as patient HTTP status code, and provider. In this case, the bundle should contain a candidate resource with a cid: identifier, location and an additional search parameter using an Atom link: <link href="http://localhost/Patient?[parameters]" rel="search"/> A search link with a root of http://localhost means to search the local resource store ETag header values, which are used for identifying and versioning the resources. In addition, a match as specified resource may be included in the parameters (which must conform to the servers capability for searching entry, as specified in its conformance statement). If the search returns no matches, by the Prefer header.

2.1.0.16.4 Accepting Other bundle types

A server process may choose to accept bundle types other than batch or transaction when POST ed to the resource normally. If [base] URL.

Bundles of type history inherently have the search returns same structure as a transaction , 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 match, the server uses this matching resource instead, and ignores to another easily using a pub/sub model. Note, however, that the submitted resource. If original transaction boundaries may not represented in a history list, and a resource may occur more than one resource is found, the transaction SHALL be rejected. once in a history list, so servers processing history bundles must have some strategy to manage this.

If For other bundle types, should the server choose to accept them, there will be no request element (note that is processing every entry will have a resource). In this case, the transaction requires version aware updates, server treats the client may need to reference what is entry as either a create or an update interaction, depending on whether it recognises the server's current version identity of the resource, which is now resource - if the client's previous version: <link href="[base]/Patient/34/history/31" rel="predecessor-version"/> A server SHOULD accept "http://localhost" in place identity of the [base] resource refers to ease processing where a valid location on the host name may be unknown (e.g. where proxies are involved). The predecessor-version is treated as if server, it were the content-location header on should treat it as an update interaction. to that location. Note: this option allows a client to delegate the matching process to the server.

2.1.15 2.1.0.17 history

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 Get GET command as shown:

  GET [base]/[type]/[id]/_history{?[parameters]&_format=[mime-type]}
  GET [base]/[type]/_history{?[parameters]&_format=[mime-type]}
  GET [base]/_history{?[parameters]&_format=[mime-type]}

The return content is a Bundle with type set to history containing the specified version history, sorted with oldest versions last, and including deleted resources, represented resources. Each entry SHALL minimally contain either a resource which holds the resource as described in bundles using it is at the method described conclusion of the interaction, or a request with entry.request.method The request provides information about the interaction that occurred to cause the new version, and allows, for XML instance, subscriber system to differentiate between create and update interactions. The principal reason a resource might be missing is that the resource was changed by some other channel rather than via the RESTful interface. If the entry.request.method is a PUT or a POST , the entry SHALL contain a resource.

The interactions create , update , and delete 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 JSON . 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.

A create interaction is represented in a history interaction in the following way:

  <entry>
    <resource>
      <Patient>
        <!-- the id of the created resource -->
        <id value="23424"/>
        <!-- snip -->
      </Patient>
    </resource>
    <request>
      <!-- POST: this was a create -->
      <method value="POST"/>
      <url value="Patient"/>
    </request>
  </entry>

Note that conditional creates, updates and deletes are converted to direct updates and deletes in a history list.

In addition to the standard _format parameter, the parameters to this interaction may also include:

_count : integer	single	Number of return records requested. The server is not bound to return the number requested, but cannot return more
_since : instant	single	Only include resource versions that were created at or after the given instant in time

The history list can be restricted to a limited period by specifying a _since parameter which contains a full date time with time zone. Servers SHALL ensure that if a client uses the feed.updated date from the last response they received as the value of the _since parameter, no versions will be missed. 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.

The updates list can be long, so servers may use paging. If they do, they SHALL use the method described in RFC 5005 (Feed Paging and Archiving) (also see Paging described below ) for breaking the list into pages if appropriate. appropriate, and maintain the specified _count across pages.

The history interaction is suitable for use with internet pub/sub systems based on rss/atom, including services such as Feedly , allowing humans to easily subscribe to notifications of updates to a resource (this is usually appropriate for low volume high knowledge resources like profiles). In addition, the history interaction can be used to set up a subscription from one system to another, so that resources are synchronized between them. Systems receiving such feeds and planning on enforcing resource integrity should note that transaction boundaries are not reflected in the history list. 2.1.16 Tag Operations Tags are attached to resources Refer to define operational behavior. When resources are exchanged directly use HTTP on the read, vread, create and update interactions, the http header "Category" is used, following the method described for Web Categories . Category: [Tag Term]; scheme="[Tag Scheme]"; label="[Tag label]"(, ...) The label portion is optional. Note that label may come before scheme. Although Category is described as a repeating header, many implementations require unique header names, so multiple tags are representing using the one header. Interaction Tag Actions read/vread The server returns all tags associated with the resource in the headers create The server stores all the tags provided in the headers update The server stores all the tags provided in the headers, and keeps any tags already associated with the Subscription resource In the other interactions, the resources are wrapped in bundles, where tags are represented in the entry.category element and servers populate these completely or process these as part of a transaction submission. The following operations provide specific support for tags: HTTP Command description GET [base]/_tags get a list of all tags GET [base]/[type]/_tags get a list of all tags used for the nominated resource type GET [base]/[type]/[id]/_tags get a list of all tags affixed to the nominated resource. This duplicates the HTTP header entries GET [base]/[type]/[id]/_history/[vid]/_tags get a list of all tags affixed to the nominated version of the resource. This duplicates the HTTP header entries POST [base]/[type]/[id]/_tags Affix tags in the list to the nominated resource POST [base]/[type]/[id]/_history/[vid]/_tags Affix tags in the list to the nominated version of the resource POST [base]/[type]/[id]/_tags/_delete Remove all tags in the provided list from the list of tags for the nominated resource POST [base]/[type]/[id]/_history/[vid]/_tags/_delete Remove tags in the provided list from the list of tags for the nominated version of the resource The tags of an old version can still be changed. Note that changing the tags on a resource does not create a new version alternate means of the resource. A tag list is represented like this in XML and JSON: <taglist xmlns="http://hl7.org/fhir"> <category term="" scheme="http://hl7.org/fhir/tag"> </taglist> { "resourceType" : "TagList", "category" : [{ "term" : "[Tag URI]",S "label" : "[Tag Label]", "scheme" : "http://hl7.org/fhir/tag" }] } Note that "resourceType" is used for consistency even though a tag list is not a FHIR "resource". system synchronization.

2.1.17 2.1.0.18 Transactional Integrity

When processing create and update operations, interactions, a FHIR server is not obliged to accept the entire resource as it is; when the resource is retrieved through a read operation interaction subsequently, the resource may be different. The difference may arise for several reasons:

• The server merged updated content with existing content
• The server applied business rules and altered the content
• The server does not fully support all the features or possible values of the resource

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 kind kinds of behaviors may be driven by security considerations. With regard to incomplete support, Clients clients can consult the server's base conformance statement profile references to determine which features or values the server does not support.

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. 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.

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.

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.

Some of these problems can be mitigated by following a pattern built on top of version-aware updates. In this pattern:

• The server provides a read operation interaction for any resource it accepts update operations interactions on
• Before updating, the client reads read s the latest version of the resource
• The client applies the changes it wants to the resource, leaving other information intact (note the extension related rules around this)
• The client writes the result back as an update operation, interaction, and is able to handle a 409 or 412 response (usually by trying again)

If clients follow this pattern, then information from other systems that they do not understand will be maintained through the update.

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.

2.1.17.1 2.1.0.18.1 Conformance

Both client and server systems SHOULD clearly document how transaction integrity is handled.

DSTU TODO: how? 2.1.18 Binary Support FHIR servers can choose to support Binary Resources

at the end point [base]/Binary. The binary end-point accepts any kind of content, such as images and other media, documents (CDA, PDF, Word etc.), plain text, XML or anything else, and stores the content as is, along with the content type provided by the HTTP headers.

Binary resources function with DSTU Note: For now, the same interactions as described above, except that there only way to document how transaction integrity is no support for the search interaction. The _format parameter has no meaning when used with binary resources: they are always represented using their original content type. Note that on GET, POST, and PUT operations, the http content-type header handled is as text in the mime type narrative portions of the binary resource, and Conformance resource. Feedback during the HTTP body Trial use period on what - if any - of this information should be computable is the resource in it's binary form. (The XML and JSON Bundle Representations for binary resources are only used in bundles). welcome.

Here is the request and response to a read operation on a CDA document: Provide feedback here .

GET /[path]/Binary/4 HTTP/1.1 Host: [server] Accept: */* HTTP/1.1 200 OK Content-Type: text/xml Access-Control-Allow-Origin: * Last-Modified: Thu, 24 Oct 2013 00:41:55 +0000 Content-Location: http://[server]/[path]/Binary/4/_history/1 <ClinicalDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:hl7-org:v3"xmlns:cda="urn:hl7-org:v3"> ... [snip] ... </ClinicalDocument>

2.1.19 2.1.0.19 Paging

If servers provide paging for the results of a search or history interaction, they SHALL conform to the this method described in (adapted from RFC 5005 (Feed Paging and Archiving) for sending continuation links to the client when returning a bundle Bundle (e.g. with history and search). search ). If the server does not do this, this then there is no way to continue paging.

This example shows the third page of a search result:

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Search Page 3</title>
  <!-- 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 

<Bundle xmlns="http://hl7.org/fhir">
  <!-- snip metadata -->
  <!-- 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.
	-->
  <link rel="self" href="http://example.org/Patient?name=peter&stateid=23&page=3"/>

  <link>
    <relation value="self">
    <url value="http://example.org/Patient?name=peter&stateid=23&page=3"/>
  </link>
  <!-- 4 links for navigation in the search. All of these are optional, but recommended -->


  <!-- 4 links for navigation in the search. All of these are optional, but recommended -->  
  <link rel="first" href="http://example.org/Patient?name=peter&stateid=23&page=1"/>
  <link rel="previous" href="http://example.org/Patient?name=peter&stateid=23&page=2"/>
  <link rel="next" href="http://example.org/Patient?name=peter&stateid=23&page=4"/>
  <link rel="last" href="http://example.org/Patient?name=peter&stateid=23&page=26"/>
  <updated>2003-12-13T18:30:02Z</updated>

  <link>
    <relation value="first"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=1"/>
  </link>
  <link>
    <relation value="previous"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=2"/>
  </link>
  <link>
    <relation value="next"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=4"/>
  </link>
  <link>
    <relation value="last"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=26"/>
  </link>


  <!-- the rest of the search results... -->  
</feed>

  <!-- then the search results... -->
</Bundle>

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.

A server MAY inform the client of the total number of resources returned by the interaction for which the results are paged using the totalResults element from the OpenSearch specification : Bundle.total .

<feed xmlns="http://www.w3.org/2005/Atom"> <title>e.g. Search Page 3</title> <os:totalResults xmlns:os="http://a9.com/-/spec/opensearch/1.1/">1432</os:totalResults> <!-- the rest of the search/history results... --> </feed>

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.

2.1.20 2.1.0.20 Intermediaries

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 HTTP specification for further detail

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 HTTP header to assist with troubleshooting.

Any agent that modifies an HTTP request or Response response content other than under the rules for HTTP proxies SHALL add a stamp to the HTTP headers like this:

  request-modified-[identity]: [purpose]
  response-modified-[identity]: [purpose]

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.

2.1.21 2.1.0.21 OMG hData RESTful Transport

This RESTful specification described here is based on the OMG Health RESTful specification (specific reference to be provided when this is published). (HData) . In this regard, FHIR functions as a Record Format Profile as described in that specification. Note the following significant factors to be aware of:

• 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 compartments behave somewhat like sections
• Because clients cannot submit new sections (POST ( POST to service URL), POST to the service URL has been re-used for the transaction interaction (difference under review)
• 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)
• Note that this specification does not repeat the rules in the hData RESTful Transport concerning the OPTIONS command on the service URL, but these rules (extra headers etc.) still apply

2.1.22 2.1.0.22 Summary

These tables present a summary of the interactions described here. Note that all requests may include an optional Accept header to indicate the format used for the response (this is even true for DELETE since an OperationOutcome may be returned).

search-all history-type tags mailbox /Mailbox (Message)

Interaction	Path	Request
		Verb	Content-Type	Body	Accept Prefer	Content-Location Conditional
read	/[type]/[id]	GET	N/A	N/A	O N/A	N/A O: ETag , If-Modified-Since , If-None-Match
vread	/[type]/[id]/_history/[vid]	GET	N/A	N/A	O N/A	N/A
conformance / or /metadata OPTIONS / GET update N/A	N/A O N/A update /[type]/[id] PUT R Resource N/A O or R create /[type] POST	R Resource N/A N/A transaction PUT / POST	R	Bundle Resource	O	N/A O: If-Match
delete	/[type]/[id]	DELETE	N/A	N/A	N/A	N/A
search create	/[type]/_search? or /[type]? /[type]	GET POST	N/A R	N/A Resource	O	N/A O: If-None-Exist
search	/ /[type]?	GET	N/A	N/A	O N/A	N/A
	validate /[type]/_validate{/[id]} /[type]/_search?	POST	R Resource O N/A application/x-www-form-urlencoded history /[type]/[id]/_history GET	N/A form data	N/A	O N/A
search-all	/[type]/_history /_search?	GET	N/A	N/A	O N/A	N/A
	history-all conformance	/_history / or /metadata	OPTIONS or GET	N/A	N/A	O N/A	N/A
tags-all /_tags GET transaction N/A	N/A O / N/A	POST tags-type	/[type]/_tags R	GET N/A Bundle N/A	O	N/A
/[type]/[id]/_tags history GET	N/A N/A /[type]/[id]/_history O	N/A GET POST	R N/A	TagList N/A	N/A	N/A
tags-delete /[type]/[id]/_tags/_delete POST R TagList history-type N/A	N/A tags-version /[type]/_history /[type]/[id]/_history/[vid]/_tags	GET	N/A	N/A	O N/A	N/A
POST R TagList history-all N/A	N/A /_history tags-version-delete	/[type]/[id]/_history/[vid]/_tags/_delete POST GET	R N/A	TagList N/A	N/A	N/A
(operation)	/$[name] , /[type]/$[name] or /[type]/[id]/$[name]	POST	R	Bundle Parameters	R N/A	N/A
		/Mailbox (Document) POST GET	R N/A	Bundle N/A	N/A	N/A
		document /Document POST R	application/x-www-form-urlencoded	Bundle form data	N/A	N/A

Note: Notes:

• N/A = not present, R = Required, O = optional. optional
• For operations defined on all resources, including direct access to the meta element, see Resource Operations

tags TagList N/A N/A 200

Interaction	Response
	Content-Type	Body	Location	Content-Location Versioning	Status Codes
read	R	R: Resource	N/A	R R: ETag , Last-Modified	200, 404, 200 , 404 , 410
vread	R	R: Resource	N/A	O 200, 404, 405 R: ETag , Last-Modified conformance	R Conformance N/A O 200, 200 , 404
update N/A N/A N/A R 200, 201, 400, 404, 405, 409, 412, 422 update create	N/A R if body	N/A O: Resource (Prefer)	R on create	O R: ETag , Last-Modified	201, 400, 404, 405, 200 , 201 , 400 , 404 , 405 , 409 , 412 , 422
transaction delete	R if body	Bundle O: OperationOutcome	N/A	N/A	200, 400, 404, 405, 409, 412, 422 200 , 204 , 404 , 405 , 409 , 412
delete create	N/A R if body	N/A O : Resource (Prefer)	N/A R	N/A R: ETag , Last-Modified	204, 405, 201 , 400 , 404 , 405 , 422
search	R	R: Bundle	N/A	N/A	200, 200 , 403 ?
search-all	R	R: Bundle	N/A	N/A	200, 200 , 403 ?
validate N/A or R N/A or OperationOutcome N/A N/A 400 conformance history	R	Bundle R: Conformance	N/A	N/A	200 , 404
history-type R Bundle N/A N/A 200 transaction history-all	R	R: Bundle	N/A	N/A	200 tags-all R TagList N/A N/A 200 tags-type R TagList N/A N/A , 400 , 404 , 405 , 409 , 412 , 422 200
R (GET) TagList history N/A	N /A R	200, 404, 410 R: Bundle	N/A (POST)	N/A	N/A N/A 200 204
tags-delete N/A N/A N/A N/A 204 history-type tags-version	R (GET)	N/A N/A 200, 404 R: Bundle	N/A (POST)	N/A	N/A N/A 200 204
tags-version-delete N/A N/A N/A N/A 204 history-all mailbox	R (Message)	R: Bundle	N/A (Document)	N/A	N/A N/A 200 204
document (operation)	N/A R	N/A R: Parameters/Resource	N/A	N/A	200

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 a are server errors and various codes associated with authentication protocols.