. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.06: DSTU 1 Ballot 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
In addition to the set of base resources, FHIR also provides a simple RESTful implementation using HTTP. 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".
Note that in this RESTful framework, transactions are performed directly on the server resource using an HTTP request/response. These HTTP calls may be authenticated against a single user account (including using OAuth), but this arrangement doesn't cater for common transaction metadata such as multiple users, responsible party, reasons, consents, etc. that are commonly encountered in healthcare. Instead, use of this RESTful implementation assumes that appropriate security and logs are managed by the client (perhaps through using ATNA), and that the server trusts the client to maintain these. One implication is that this RESTful framework is only suitable for use where such trust relationships exist (e.g. in a single institution) and is not suitable where such trust does not exist (e.g. state & national EHR systems and health record systems that support disparate systems). Similarly, this simple RESTful interface has no support for explicit archiving and similar functions. Use-cases where these kind of features are required should consider a messaging or SOA-based approach or some kind of profiled REST interface, such as hData.
The following logical interactions are supported:
| Instance | |
| 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 the resource |
| Manager | |
| create | Create a new resource with a server assigned id |
| search | Search the resource type based on some filter criteria |
| updates | Get a list of prior updates to resources of this type, optionally with some filter criteria |
| System | |
| validate | Check that the content would be acceptable as an update |
| conformance | Get a conformance statement for support of this resource type |
| batch | Update or create a set of resources |
Note that while these same logical interactions are defined on all resources, applications are not required to implement all of them, except for the conformance statement: applications must provide a conformance statement that says what interactions are supported for any resource types that they support.
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 optional path may end with a trailing slash or not. Each resource type defined in this specification has a manager (or "entity set") that lives at the address "/[name]" where the name is the name of the resource type in lower case. For instance, the resource manager for the type "Patient" will live at:
http://server/path/patient
All the logical operations are defined relative to this service root URL. Note that this means that given the address of any one FHIR resource on a system, the correct address for all the other resources may be determined. However since application URLs may change and because in some uses of FHIR within internal eco-systems, local configuration may dictate that the provider of a resource is different to that claimed by any particular provider or consumer, applications may need to replace Service Root URLs.
Note: All URLs (and ids that form part of the URL) defined by this specification are case sensitive.
Each resource has an associated set of resource metadata elements. These map to the http request and response using the following fields:
| Metadata Item | HTTP Response Header |
|---|---|
| Id | The Id is represented explicitly in the URL |
| Version Id | 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 |
| Last Modified Date | HTTP Last-Modified header |
For this specification, normal HTTP security and authentication rules apply. The Service Root URL will specify whether SSL is required. HTTP authentication may be required by the server, possibly including the requirement for client certificates. It is a matter of application requirements and local configuration whether all interactions run under the account of a trusted system user, whether each interaction runs under the account of the individual user or whether some other arrangement is required.
OAuth may be used to provide security. Applications are recommended to use the variants of the OAuth protocol that do not require URL parameters, but these may be used if necessary.
This specification makes some rules about the use of specific HTTP status codes in some particular circumstances where the status codes must 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. Note that some security layers may issue redirects which should not be interpreted to change the location of the resource itself (a common web programming error).
The formal MIME-type for FHIR resources is text/xml+fhir (still to be registered) and SHOULD be use by clients and servers. Servers are required to support the XML format of the resources defined in this specification, but may support other alternatives, including the informative JSON representation. Servers must support server-driven content negotiation as described in section 12 of the HTTP specification, but in order to support various implementation limitations, may choose to support the (?$format=) parameter to specify alternative response formats by their MIME-types. For the $format parameter, the values "xml", "text/xml" and "text/xml+fhir" must be interpreted to mean the normative XML format defined by FHIR and "json" and "application/json" must be interpreted to mean the informative JSON format.
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 MUST explicitly set the character encoding to UTF-8 using the '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.
The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET operation as shown:
GET [service-url]/[resourcetype]/{@id} (?$format=mimeType)
This returns a single instance with the content specified for the resource type. This url may be accessed by a browser. The logical id is preceded by a "@" to make parsing the url easier. The possible values for the id itself are described in the id type. Servers are required to return a content-location header with the response which is the full version specific url (see vread below) 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.
The vread interaction preforms a version specific read of the resource. The interaction is performed by an HTTP GET operation as shown:
GET [service-url]/[resourcetype]/{@id}/history/{@vid} (?$format=mimeType)
This returns a single instance with the content specified for the resource type for that version of the resource. Servers may return a content-location header with the response which is the url requested and a Last-Modified header.
The version id is an opaque identifier that conforms to the same format requirements as a resource id. The id may have been found by performing a history operation (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. The vread interaction for a version that marks the deletion of the resource should succeed as long as a correct version identifier is provided, in which case a 410 status code is returned.
Servers SHOULD support a version specific retrieval of the current version of the resource even if they are unable to support access to previous versions.
The update interaction changes an existing resource or creates a new resource if it doesn't already exist. The update interaction is performed by an HTTP PUT operation as shown:
PUT [service-url]/[resourcetype]/{@id} (?$format=mimeType)
If the operation is successful, the server must return 200 OK, along with a copy of the newly updated resource (which might not be the same as that submitted) with the response, along with a Last-Modified header, and a Content-Location header that refers to the version created by the updated operation.
Servers are permitted to reject update operations because of integrity concerns or business rules implemented on the server, and return HTTP status codes accordingly.
In particular, servers may choose to implement version-aware updates, where the only updates that are accepted quote the current version of the resource. In this case, the client must submit the currently correct version specific URL in the Content-Location in the PUT request. If the value is missing, the server SHALL return a 412 Preconditions failed response. Clients SHOULD submit a proper Content-Location header and SHALL correctly understand a 409 response as an update conflict.
The following resources may require special handling on the server when updated (whether directly or as part of a batch):
Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):
The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE operation as shown:
DELETE [service-url]/[resourcetype]/{@id}
A delete operation means that non-version specific reads of a resource return a 410 error and that the resource is no longer found through search operations. Upon successful deletion the server should return 204 (No Content). If the server refuses to delete resources of that type on principle, then it should return the status code 405 method not allowed. 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 existe on the server, the server must return 404 (Not found). Performing this operation on a resource that is already deleted has no effect, and should return 204. Resources may be undeleted by PUTting an update to them subsequent to the deletion.
Many resources have a status element that overlaps with the idea of deletion. Each resource type defines what the semantics of the deletion operations are. If no documentation is provided, the deletion operation should be understood as deleting the record of the resource, with nothing about the state of the real-world corresponding resource implied.
The following resources may require special handling on the server when deleted (whether directly or as part of a batch):
The history interaction retrieves the history of the resource. The interaction is performed by an HTTP Get operation as shown:
GET [service-url]/[resourcetype]/{@id}/history (?$format=mimeType)
The return content is an Atom feed containing the version history for that resource, sorted with oldest versions first.
The create interaction creates a new resource. The interaction is performed by an HTTP POST operation as shown:
POST [service-url]/[resourcetype] (?$format=mimeType)
The server returns a 201 Created, along with a copy of the newly created resource (which might not be the same as that submitted) with the acknowledgement, along with a version-aware Location header which contains the new location and id of the created resource:
Location: [service-url]/[resourcetype]/{@new-id}/history/{@new-vid}
When the payload data is incorrect and cannot be used to create a new resource, the server returns a 400 Bad Request. Note: If the client wishes to have control over the id of a newly submitted resource, it should use the update operation instead.
The following resources may require special handling on the server when created (whether directly or as part of a batch):
Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):
This interaction searches a resource type based on some filter criteria. The interaction is performed by an HTTP Get operation as shown:
GET [service-url]/[resourcetype]/search?parameters (&format=mimeType)
Because of the way that some user agents treat POST requests, POST submissions are also allowed, though the semantics are exactly the same as a GET operation. Search operations take a series of parameters that are encoded in the URL or as an x-multi-part-form submission for a POST. The return content is an Atom feed containing the results of the search as a list of resources in a defined order. This specification does not assign any particular meaning to the order of the resources.
Each FHIR resource type defines a set of applicable search parameters with their names, types, repeat behaviour, and meanings. Parameter values are not case-sensitive. In addition, the following common search parameters apply to all resource types:
| $page : integer | single | Starting offset of the first record to return in the search set |
| $count : integer | single | Number of return records requested. The server is not bound to conform |
| $id : token | single | The logical resource id associated with the resource (must be supported by all servers) |
| $include : token | union | See below |
| integer | Search parameter must be a simple whole number |
| string | Search parameter is a simple string, like a name part (search usually functions on partial matches) |
| text | Search parameter is on a long string (i.e. a text filter type search) |
| date | Search parameter is on a date (and should support -before and -after variants). The date format is the standard XML format, though other formats may be supported |
| token | Search parameter is on a fixed value string (i.e. search has an exact match) |
| qtoken | Search parameter is a pair of fixed value strings, namespace and value, separated by a "#". The namespace is usually a uri, such as one of the defined code systems and is optional when searching |
| single | The search parameter may only occur once |
| union | When the search parameter occurs more than once, match resources with any of the values |
| intersection | When the search parameter occurs more than once, match resources with all of the values |
Parameters may be "chained" by appending them together separated by "." following a logical path through a graph of related resources. For instance, given that the resource "LabReport" has a search parameter named patient, which is a reference to a "Patient" resource, and the Patient resource includes a parameter person, which is a reference to the "Person" resource, and the person resource has a search parameter name which searches on patient name, then the search
LabReports/search?patient.person.name=peter
is a request to return all the lab reports that have a subject whose name includes "peter".
Clients may request that the server return additional resources related to the search results, in order to reduce the overall network query time. A typical case where this is useful is where the client is querying on the patient resource, but for every patient resource returned, the client will also need the person resource that the patient refers to. The client requests this by providing one or more $include parameters.
Each $include parameter specifies a path in a URL (as an XPath value):
LabReports/search?$include=LabReport/patient&$include=Patient/subject
For each returned resource, the server executes the XPath statement, and, if it matches one or more resource references, and it is able to locate the targets, appends the target resource to the return result. Note that $include parameters may be recursive. For instance, a client may request to return all the patients associated with a search on lab reports, and then to include all the person resources for the patients returned, as shown above.
If the $include path matches a general url rather than a resource reference, the server may elect to include the target of the url reference in the returned result.
Servers have considerable discretion with regards to supporting to search:
If more sophisticated searching is required, a FHIR-based service interface can be defined to enable the workflow and functionality desired.
The updates interaction retrieves a list of the resources of a particular type, ordered by the date of last update in reverse (most recently changed first). The interaction is performed by an HTTP Get operation as shown:
GET [service-url]/[resourcetype] (?$format=mimeType)
The return content is an Atom feed containing a list of resources, sorted with oldest updates first. Each resource only appears once, with the most recent version in the list.
The updates list can be restricted to a limited period by specifying a $last parameter which contains a full date time with timezone. This only includes resources that have changed at or after the given date. Servers must ensure that if a client uses the feed.updated date from the last response as the value of the $last parameter, it will not miss any updates. 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 a precision finer than by second. Additional parameters can be used to filter the updates list using the search parameters defined by the resource type.
The validate interaction checks whether the attached content would be acceptable as an update to an existing resource. The validation operation may be the first part of a light two- phase commit process. The interaction is performed by an HTTP POST operation as shown:
todo: harmonise these with the RLUS REST specification
POST [service-url]/[resourcetype]/validate/{@id}
The content is first checked against the general specification and against the conformance profile that applies to the application. How much checking is performed is at the discretion of the server. Then the resource is considered as a proposed update and additional instance specific rules such as referential integrity and update logic (including version control) are applied as well. The return content has one of the following values:
Unless the result is 200 OK, the response must include an Issue Report that lists the issues found on validation.
The validation operation has complex semantics and rules; see the full discussion of the operation in the OMG REST specification for further details.
The conformance interaction retrieves the application's conformance statement for the resource. The interaction is performed by an HTTP OPTIONS or a GET operation as shown:
OPTIONS [service-url] (?$format=mimeType) GET [service-url]/metadata (?$format=mimeType)
Applications SHALL return a Conformance Resource that specifies which resource types and operations are supported. If a 404 Unknown is returned, FHIR is not supported on the nominated service url. The GET operation is defined because not all client libraries are able to perform an OPTIONS operation. Additional parameters that are required to be returned with the OPTIONS command are defined in the OMG hData RESTful Transport specification.
Servers may choose what content to return when they receive a GET operation on the Service Root URL. Generally some page that guides human manual interaction with the server would be appropriate.
The batch interaction submits a set of resources to be updated or created on the server. This interaction has two principle uses: to support push-based pub/sub, and to allow multiple resources to be updated/created in a single transaction. Multiple different types of resources may be submitted, including a mix of new and existing resources. The interaction is performed by an HTTP POST operation as shown:
POST [service-url] (?$format=mimeType)
The content of the post submission is a resource bundle in either XML or JSON. The resources in the bundle are each processed separately as if they were an individual create or update appropriately, along with the normal processing for each (such as version aware updates). Servers SHALL either accept all resources and return a 200 OK, along with a response bundle, 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.
When a bundle is submitted in a batch operation, all the resources must be identified. If the identity of the resource matches an existing or possible resource location on the server, the server should treat this entry as an update operation (i.e. PUT to the given resource). If the identity is not one that the server recognises, the server should treat the operation as a create operation (i.e. POST to the given resource manager), and create a new identity for the submitted resource.
If the server must assign a new identity when it accepts the resource, it must also update any references to that resource in the same batch as they are processed. References to resources that are not part of the batch are left untouched. If a resource in the batch carries a version-specific id (using its self-link), any version-specific references to it must also be updated.
Note that this allows clients to assign temporary (version-specific) ids to new resources and refer to them from within the batch while the server will update these temporary ids after their creation. This is especially useful in RESTful scenario's where one would otherwise need multiple operations, possibly leading to loss of referential integrity (e.g. when storing a Provenance resource and its corresponding target resource).
In order to allow the client to know how newly created resources are now identified, the server must return a bundle containing the same resources in the order that they were submitted.
FHIR servers can choose to offer support for purely binary resources at the end point [service-url]/binary. The binary end-point accepts any kind of resources, and stores them as is, along with the content type provided by the HTTP headers.
The binary resource functions with the same operations as described above, except that there is no support for the search operation, nor can filtering parameters be used on the updates function. The $format parameter has no meaning when used with binary resources- they are always represented using their original content type.
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 rogue caching.
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 must mark the http header to assist with troubleshooting.
Any agent that modifies an HTTP request or Response content other than under the rules for HTTP proxies must add a stamp to the HTTP headers like this:
request-modified-[identity]: [purpose] response-modified-[identity]: [purpose]
The identity must be a single token defined by the administrator of the agent that will sufficiently identify the agent in the context of use. The header must specify the agent's purpose in modifying the content. End point systems must not use this header for any purpose. Its aim is to assist with system troubleshooting.
This RESTful specification described here is based on the OMG Health RESTful specification (specific reference to be provided when this is published). In this regard, FHIR functions as a Record Format Profile as described in that specification. Note the following significant factors to be aware of:
This is an old version of FHIR retained for archive purposes. Do not use for anything else
Implementers are welcome to experiment with the content defined here, but should note that the contents are subject to change without prior notice.
© HL7.org 2011 - 2012. FHIR v0.06 generated on Tue, Dec 4, 2012 00:04+1100. License