. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.05: DSTU 1 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 the set of base resources, FHIR also provides a RESTful implementation using HTTP - an implementation of the OMG Health RESTful specification. 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 protocol 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. These types 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 | 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 |
| validate | Check that the content would be acceptable as an update |
| Manager | |
| updates | Get a list of prior updates to resources of this type, optionally with some filter criteria |
| search | Search the resource type based on some filter criteria |
| create | Create a new resource with a server assigned id |
| System | |
| conformance | Get a conformance statement for support of this resource type |
Note that while these same logical interactions are defined on all resources, applications are not required to implement all of them. Applications must provide a conformance statement that says what interactions are supported.
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 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 the service root URL below. 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: except for the Service Root Portion of the URL, all the URLs (and ids that form part of the URL) defined by this specification are case sensitive and are required to be in lowercase.
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 |
|---|---|
| Version Id | The Version Id is represented by the full canonical URL in the master location (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 |
| Master Location | HTTP Content-Location 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.
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 the content-type negotiation support described by the HTTP specification, but in order to support various implementation limitations, may choose to support the (?format=) parameter to specify alternative return formats by their mime types. For the format parameter, the mime types text/xml & text/xml+fhir must be interpreted to mean the normative XML format defined by FHIR and application/json must be interpreted to mean the informative JSON format.
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.
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. 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 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 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)
The server must return 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 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 incorrect, the server SHALL return a 412 Preconditions failed response. Clients SHOULD submit a proper Content-Location header and SHALL correctly understand a 412 response as an update conflict.
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. 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 409 Conflict. 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 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. ToDo: how deletions are represented.
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 are applied as well. The return content has status 200 OK if the content validates ok or 409 Conflict, with the following content:
<validation xmlns="http://hl7.org/fhir">
<error mand type="string">General error message</error>
<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 validation operation has complex semantics and rules. Implementers wishing to use this operation should consult the full discussion of the operation in the OMG REST specification.
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 list of resources, sorted with oldest updates first.
The updates list can be restricted to a limited period by the Last-Modified header. Additional parameters can be used to filter the updates list using the search parameters defined by the resource type.
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. Each FHIR resource type defines a set of applicable search parameters with their meanings and servers may declare additional parameters in their conformance statements. In addition, the following common search parameters apply to all resource types:
| n : integer | Starting offset of the first record to return in the search set |
| count : integer | Number of return records requested. The server is not bound to conform |
| id : id | An identifier associated with the resource |
It is at the discretion of the server how many results to return, though the client may request a particular number with the 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 its usefulness. Note that which parameters to support is at the discretion of the server.
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.
If more sophisticated searching is required, a FHIR-based service interface can be defined to enable the workflow and functionality desired. At this time, support for messaging-based queries is not expected to be needed in FHIR.
| 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 into a long string (i.e. a text filter type search) |
| date | search parameter is onto a date (and should support -before and -after variants) |
| 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 |
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 copy of the newly created resource (which might not be the same as that submitted) with the acknowledgement, along with a Location: header which also contains the new location and id of the created resource:
Location: [service-url]/[resourcetype]/{new-id} version aware....
The resource id element SHALL not be present. If the client wishes to specify the id of the submitted resource, then it should use the update operation instead.
The conformance interaction retrieves the application's conformance statement for the resource. The interaction is performed by an HTTP OPTIONS operation as shown:
OPTIONS [service-url] (?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.
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 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 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 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.05 generated on Sun, Sep 9, 2012 03:28+1000. License