. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.01: Historical Archive Draft). 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 defining a set of base resources, FHIR also provides a 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 this RESTful framework adheres as closely as possible to the REST principles. Transactions are performed directly on the server resource using an HTTP request/response. The HTTP calls may be authenticated against a single user account (including using OAuth), but this doesn't cater for common transaction metadata such as multiple users, responsible party, reasons, consents etc that is commonly encountered in healthcare. Instead, it is assumed that appropriate security and logs are managed by the client (perhaps through using ATNA), and the server trusts the client to maintain these. One implication of this is that this RESTful framework is only suitable for use where such trust relationships exist (e.g. in a single institution), and not suitable where such trust does not exist (e.g. state & national EHR systems, and general internet-based ecosystems). Similarly, this simple RESTful interface has no support for explicit archiving, for instance. These type of more sophisticated usages 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 | A version specific read of the resource |
| update | Update an existing resource by it's id (or create it if it is new) |
| delete | Delete a resource |
| validate | Check that the content would be acceptable as an update |
| history | Retrieve the update history for the resource |
| transaction | Support for specific transactions defined on the resource |
| Manager | |
| search | Search the resource type based on some filter criteria |
| create | Create a new resource with a server assigned id |
| updates | Get a list of updates to resources of this type, optionally with some filter criteria |
| transaction | Support for specific transactions defined on the resource type |
| conformance | Get a conformance statement for support of this resource type |
| schema | Get the XML schema for this resource |
Note that while these same logical interactions are defined on all resources, applications are not required to implement all of them. An application's conformance statement must say what logical interactions are supported.
Each resource lives at a specific location with a known URL which is automatically determined from the id, the resource type, and the base url of the system.
The concept of the base URL is defined because because this specification defines an interface rather than any particular system. The base URL is the address at which all the resources defined by this interface are found. The base URL takes the form of
http(s)://server/path
The path may end with a trailing slash or not. Each resource defined in this specification has a manager that lives at the address "/[type name]" where type name is the name of the type in lower case and plural. So, for instance, the resource manager for the type "Patient" will live at:
http://server/path/patients
Note that applications may need to remove the trailing slash from the base URL when appending the resource address. All the logical operations are provided relative to the address of the resource and defined in these terms below. Note that this means that given the address of any one resource on a system, the correct address for all the other resources may be determined. However since application URLs may change, and because local configuration may dictate that the provider of a resource is different to that claimed by any particular provider or consumer, applications should be adroit at replacing base URLs.
For all interactions, if the requested resource is returned as requested, the HTTP status 200 OK should be used (except for "create" where the status code should be 201). If the resource is not known, the server should return an HTTP status code 404 Not Found. Other HTTP errors may be returned as appropriate.
An HTTP redirect should not be used to indicate that the master id has changed. This is because the ids are treated as stable references elsewhere and used for matching. Changing an id will cause problems with this matching. Redirects may be issued to redirect to a new base URL, or to a master system for a given resource.
Each resource has an associated set of resource metadata. These map to the http request and response using the following fields:
| Metadata Item | HTTP Response Header |
|---|---|
| Version Id | ETag |
| Last Modified Date | Last-Modified |
| Master Location | Content-Location |
For this specification, normal HTTP security and authentication rules apply. The base URL will specify whether SSL is required. HTTP authentication, including possibly the requirement for client certificates, may be required by the provider. It is a matter of application requirements and local configuration whether all interactions run under the account of a trusted system user, or whether each interaction runs under the account of the individual user.
All the URLs defined below may be extended to support the OAuth protocol.
This same RESTful protocol may be used with either the XML or JSON representations defined for resources. The mime types text/xml and application/json are to be used in the HTTP Content-Type or Accept header respectively to indicate which form is the requested or returned content takes . In addition, the URLs defined below may have the file extensions .xml or .json may be appended to the URL where appropriate, as indicated by (.ext) below. For reasons of general compatibility, servers and clients may accept application/xml, but must specify text/xml themselves.
Servers are required to support the XML form. Support for the JSON format is optional. Servers must support the Content-Type and Accept headers. Because of established browser behaviour, file extensions in the URL overrule the values specified in the headers.
The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET operation as shown:
GET [baseurl]/[resourcetype]/{@id} (.ext)
This returns a single instance with the content that which is specified for the resource type. This url may be accessed by a browser. The id is preceded by a ":" to make parsing the url easier. The possible values for the id itself are described in the Resource Type. The http headers ETag, and Last-Modified must be returned by the server, and the Content-Location should be returned.
The vread interaction preforms a version specific read of the resource. The interaction is performed by an HTTP GET operation as shown:
GET [baseurl]/[resourcetype]/{@id}/version-{:vid} (.ext)
This returns a single instance with the content that which is specified for the resource type. This url may be accessed by a browser. The http headers ETag, and Last-Modified, must be returned by the server, and are the values that apply for this version of the resource.
The version id is an opaque identifier that conforms to the same format requirements as a resource id. The id may be found by performing a history operation (see below), by recording the ETag return with a normal fetch operation, or from a version specific reference in a content model. The vread interaction should succeed even after a resource is deleted as long as a correct version identifier is provided.
The update interaction changes an existing resource, or creates a new resource of it doesn't already exist. The update interaction is performed by an HTTP PUT operation as shown:
PUT [baseurl]/[resourcetype]/{@id} (.ext)
The server returns a copy of the newly updated resource (which may not be the same as that submitted) with the response.
Servers may choose to require version checking, and only accept submitted updates that have an If-Match header that contains a matching version id for the current version of the resource. According to the http specification, it's up to the client to decide whether to provide an If-Match header, and if it does, the server must observe it. On normal update operations the client should not provide an If-Match header, and if the server wishes to receive it, it should return a 412 error with the words "If-Match" in the response text. Upon receiving this error, the client should resubmit with the If-Match header, if it is able. The Last-Modified dateTime may not suitable for concurrency checking as it only has a resolution limit of per-second, and there are other problems with dates as well.
The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE operation as shown:
DELETE [baseurl]/[resourcetype]/{@id} (.ext)
Servers may refuse to delete a resource depending on the resource type and/or contents, and on audit requirements. If a 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 412 Expectation Failed.
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 operation as shown:
POST [baseurl]/[resourcetype]/validate
POST [baseurl]/[resourcetype]/validate/{@id}
In the first case, the content is checked against the general specification and against the conformance profile that applies to the application. In the second case, the validation occurs as if the resource were submitted as an update, and additional instance specific things such as referential integrity and update rules are applied as well. The return content has status 200 OK if the content validates ok, or 412 Precondition Failed, with the following content:
<validation xmlns="http://www.hl7.org/fhir">
<error mand type="string">General error message</errror>
<messages type="list"> <!-- Zero+ -->
<message>
<path opt type="string"xpath to the issue</path>
<error mand type="string">Description of the problem</error>
</message>
<messages>
</validation>
The history interaction retrieves the history of the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/{@id} (.ext)?view=history
The return content is an Atom feed aggregration containing the version history for that resource, sorted with oldest versions first.
This interaction searches the resource type based on some filter criteria. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/search (.ext)
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. Each resource type defines the applicable search parameters, and servers may declare additional parameters in their conformance statements. In addition, the following common search parameters apply to all resource types:
| n | Starting offset of the first record to return in the search set |
| count | Number of return records requested. The server is not bound to conform. |
The search results may be divided into a number of pages using offsets. It is at the discretion of the server how many results to return, though the client may request a particular number of a count parameter. If the client wishes for more results, it should use the n parameter. More generally, the client uses parameters to narrow the search and increase it's usefulness. Note that which parameters to support is at the discretion of the server.
The return content is an Atom feed aggregration containing the results of the search in a defined order. This specification does not assign any particular meaning to the order of the resources.
The create interaction creates a new resource. The interaction is performed by an HTTP POST operation as shown:
POST [baseurl]/[resourcetype] (.ext)
The server returns a a copy of the newly created resource (which may not be the same as that submitted) with the acknowledgement, along with a Location: header which also contains the id of the created resource:
Location: [baseurl]/[resourcetype]/{new-id} (.ext)
The client may submit the content with or without an id included. If the submitted resource contains an id, the server must either honor the requested id, or return a 409 Conflict if a resource already exists by that id, or a 403 Forbidden if it will not honor client defined ids at all
The updates interaction retrieves a list of changes to the resource type. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/updates (.ext)
The return content is an Atom feed aggregration containing the update history for that resource type, sorted with oldest updates first.
The client can use parameters to filter the update list. The following table summarises ths search parameters:
| since | The time from which to return new updates |
| from | A version Id (e-tag value) from which to return updates |
The transaction interaction provides support for specific transactions defined against the resource by this specification. The transaction interaction is supported on both individual resources and the type:
POST [baseurl]/[resourcetype]/transaction/[name](.ext)
POST [baseurl]/[resourcetype]/transaction/{@id}/[name](.ext)
The name of the transaction, along with the content model of the request and response will be specified against each resource when the possible transactions are defined throughout this specification.
The conformance interaction retrieves the application's conformance statement for the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/conformance (.ext)
For the return content, see the Conformance Resource. If a 404 Unknown is returned, the resource is not supported, and no other interactions are implemented.
The schema interaction retrieves a w3c schema for the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/schema.xsd
The return content is a W3C schema that describes the resource. The schema does not have to be the one defined with this specification; it can eliminate elements not supported by the server, and explicitly define extensions supported by the server. However the xml format it describes must be consistent with the rules defined in this specification.
The HTTP protocol may be routed through an HTTP proxy such as squid. Such proxies are transparent to the applications, though implementors 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 change the content and/or destination of the HTTP exchange. Such agents are allowed, but are bound to the conform to this specification. In order to assist with troubleshooting, any agent that modifies an HTTP request or Response content must add a stamp to the HTTP headers like this:
request-modified-[identity]: [purpose] response-modified-[identity]: [purpose]
The identity must 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 agents purpose in modifying the content. End point systems must not use this header for any purpose; it's aim is to assist with system troubleshooting.
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.01 generated on Mon, May 14, 2012 09:48+1000.