2.1 RESTful による HTTP アクセス

Home ＞ Implementation ＞ RESTful API [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. 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 interactions and resources are supported.

The following logical interactions are defined:

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 interactions are defined relative to this service root URL. I propose: Note: If address of any one FHIR resourse on a system is known, the address of other resources may be determined. However applications may need to replace Service Root URLs. This may be needed as application URLs may change or in 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.

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

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

See HTTP Security.

This specification makes rules about the use of specific HTTP status codes in 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, 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.

The formal MIME-type for FHIR resources is application/fhir+xml (still to be registered) and SHOULD be use by clients and servers. 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 "application/fhir+xml" must be interpreted to mean the normative XML format defined by FHIR and "json", "application/json" and "application/fhir+json" must be interpreted to mean the informative JSON format. The applicable content type also depends on whether a bundle or single resource is communicated:

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 command 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. Systems that do not track deleted records will treat deleted records as an unknown resource.

The vread interaction preforms a version specific read of the resource. The interaction is performed by an HTTP GET command 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.

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 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 Not Allowed error.

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

PUT [service-url]/[resourcetype]/{@id} (?_format=mimeType)

If the interaction is successful, the server must return either a 200 OK if the resource was updated, or a 201 Created if the resource was created, 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 Location and Content-Location header that refers to the specific version created by the update interaction.

Servers are permitted to reject update interactions because of integrity concerns or business rules implemented on the server, and return HTTP status codes accordingly (usually 422).

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.

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
• 405 Method Not allowed - the resource did not exist prior to the update, and the serer does not allow client defined ids
• 409/412 - version conflict management - see above
• 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

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

DELETE [service-url]/[resourcetype]/{@id}

A delete interaction means that non-version specific reads of a resource return a 410 error and that the resource is no longer found through search interactions. 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 exist on the server, the server must return 404 (Not found). Performing this interaction 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 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.

The create interaction creates a new resource in a server assigned location. If the client wishes to have control over the id of a newly submitted resource, it should use the update interaction instead. The create interaction is performed by an HTTP POST command 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.

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

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 [service-url]/?parameters (&_format=mimeType)

To search a single resource type:

GET [service-url]/[resourcetype]/(?parameters) (&_format=mimeType) GET [service-url]/[resourcetype]/search(?parameters) (&_format=mimeType)

To search a compartment:

GET [service-url]/[compartment]/@[id]/*?parameters (&_format=mimeType) GET [service-url]/[compartment]/@[id]/[resourcetype]?parameters (&_format=mimeType)

Because of the way that some user agents treat GET and POST requests, POST submissions are also allowed with 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 pairs encoded in the URL (or as an x-multi-part-form submission for a POST). (See W3C HTML forms). Searches are processed as specified for the Query handling mechanism.

If the search fails, the return value is a status code 4xx or 5xx with an OperationOutcome. If the search succeeds, the return content is an Bundle 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 RFC 5005 (Feed Paging and Archiving) (also see below) for breaking the list into pages if appropriate.

The validate interaction checks whether the attached content would be acceptable as an update to an existing resource. The validation interaction may be the first part of a light two- phase commit process. The interaction is performed by an HTTP POST command as shown:

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 additional checking over the normal create and update interactions 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:

• 400 Bad Request - resource could not be parsed or had some basic FHIR validation error
• 200 OK - resource passed all validation rules
• 422 Unprocessable Entity - the resource was valid, but it violates applicable FHIR profiles or server business rules

Unless the result is 200 OK, the response must include an OperationOutcome resource that lists the issues found on validation.

The validation interaction has complex semantics and rules; see the full discussion of the interaction in the OMG hData REST specification for further details.

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 [service-url]/metadata (?_format=mimeType) OPTIONS [service-url] (?_format=mimeType)

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, 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. Additional parameters that are required to be returned with the OPTIONS command are defined in the OMG hData RESTful Transport specification.

Note that Servers may choose what content to return when they receive a GET command on the Service Root URL. Generally some page that guides human manual interaction with the server would be appropriate.

A server may also choose to provide the standard set of interactions defined here on the Conformance Resource, which means that it stores and manages a set of conformance statements. This set of managed conformance statements - one or more conformance statements from various sources - should not be confused with the server's own conformance statement, that describes how it actually works, which is what is returned from the conformance interaction.

The transaction interaction submits a set of resources to be updated, created or deleted on the server. This interaction allows multiple resources to be updated/created in a single transaction. Multiple resources of the same or different types may be submitted, and they may be a mix of new and existing resources. The interaction is performed by an HTTP POST command as shown:

POST [service-url] (?_format=mimeType)

The content of the post submission is a resource bundle. The resources in the bundle are each processed separately as if they were an individual create, update or delete as described below, along with the normal processing for each (such as tracking tags, verification and 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. The outcome of the processing the transaction SHALL not depend on the order of the resources in the transaction. Note that this means that 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.

When a bundle is submitted in a transaction interaction, all the resources have an identity specified in the bundle. 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 interaction (i.e. PUT to the given resource). If the identity is not one that the server recognises as a resource location it can use, the server should treat the interaction as a create interaction (i.e. POST to the given resource type URL), and create a new identity for the submitted resource. For clarity, when the client intends a resource to have a transient identity that the server must replace, it should use a cid: url on the resource. Note that the client must provide an identity in the bundle entry.id, but may also provide a version specific identity the atom "self" link, and may refer to this for version specific references. Deleted resources are those marked clearly using the method described for XML or JSON.

A transaction may include references from one resource to another in the bundle, which may include circular references where resources refer to each other. If the server assigns a new identity to any resource in the bundle, 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 to it must also be 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.

Note that this allows clients to assign temporary (version-specific) ids to new resources and refer to them from within the bundle 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 interactions, possibly leading to loss of referential integrity (e.g. when storing a Provenance resource and its corresponding target resource), or, on document repositories, a document index entry and its accompanying document.

In order to allow the client to know how newly created resources are now identified for future reference, the server must return a bundle containing the results of processing the resources in the same order that they were submitted.

The application constructing a bundle may not be sure whether a particular resource will already exist at the time that the transaction is executed; this is typically the case with reference resources such as patient and provider. In this case, the bundle should contain a candidate resource with a cid: identifier, and an additional search specifier using an Atom link:

<link href="http://localhost/patient/search?[parameters]" rel="search"/>

A search link with a root of http://localhost means to search the local resource store for a match as specified in the parameters (which must conform to the servers capability for searching as specified in its conformance statement). If the search returns no matches, the server process the resource normally. If the search returns one match, the server uses this matching resource instead, and ignores the submitted resource. If more than one resource is found, the transaction must be rejected.

If the server that is processing the transaction requires version aware updates, the client may need to reference what is the server's current version of the resource, which is now the client's previous version:

<link href="[url]/patient/@34/history/@31" rel="predecessor-version"/>

The predecessor-version is treated as if it were the content-location header on an update interaction.

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

GET [service-url]/[resourcetype]/{@id}/history (?_format=mimeType) GET [service-url]/[resourcetype]/history (?_format=mimeType) GET [service-url]/history (?_format=mimeType)

The return content is a Bundle containing the specified version history, sorted with oldest versions last, and including deleted resources.

The history list can be restricted to a limited period by specifying a _since parameter which contains a full date time with timezone. Servers must 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) for breaking the list into pages if appropriate.

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 synchronised between them. Systems receiving such feeds and planning on enforcing resource integrity should note that transactionboundaries are not reflected in the history list.

Tags are attached to resources to define operational behaviour. 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 URI]; scheme="http://hl7.org/fhir/tag"; 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.

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:

The tags of an old version can still be changed. Note that changing the tags on a resource does not create a new version of the resource. A tag list is represented like this in XML and JSON:

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 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 the same interactions as described above, except that there 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.

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

This example shows the third page of a search result:

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 using the totalResults element from theOpenSearch specification:

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.

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

• 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
• The FHIR resource id maps to the hData document name by prepending "@"
• Because clients cannot submit new sections (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

These tables present a summary of the interactions described here.

Note: N/A = not present, R = Required, O = optional.

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