This page is part of the FHIR Specification (v0.5.0: DSTU 2 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

2.2.0 Extended Operations on the RESTful API

The RESTful API defines a set of common interactions performed on a repository of typed resources (read, update, search, etc). These interactions follow the RESTful paradigm of managing state by Create/Read/Update/Delete actions on a set of identified resources. While this approach solves many use cases, there is some specific functionality that can be met more efficiently using an RPC-like paradigm, where named operations are performed with inputs and outputs. This specification describes a light operation framework that seamlessly extends the RESTful API.

Operations have the following general properties:

• Each operation has a name
• Each operation has a list of 'in' and 'out' parameters
• The parameters are either resources, data types or search parameters
• The operations are subject to the same security arrangements as the RESTful API
• The URIs for the operation end points are based on the existing RESTful API address scheme
• The operations may make use of the existing repository of resources in their definitions
• Operations are performed against a specific resource, a resource type, or the whole system

2.2.0.1 FHIR defined Operations

This specification defines several operations:

Validate a resource	[base]/[Resource]/$validate | [base]/[Resource]/[id]/$validate
Access a list of profiles, tags, and security labels	[base]/$meta | [base]/[Resource]/$meta | [base]/[Resource]/[id]/$meta
Add profiles, tags, and security labels to a resource	[base]/[Resource]/[id]/$meta-add
Delete profiles, tags, and security labels for a resource	[base]/[Resource]/[id]/$meta-delete
Generate a Document	[base]/Composition/$document
Concept Translation	[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate
Batch Mode Translation	[base]/ConceptMap/$batch
Closure Table Maintenance	[base]/$closure
Fetch Encounter Record	[base]/Encounter/[id]/$everything
Fetch Patient Record	[base]/Patient/$everything | [base]/Patient/[id]/$everything
Populate Questionnaire	[base]/Questionnaire/$populate | [base]/Questionnaire/[id]/$populate
Build Questionnaire	[base]/StructureDefinition/$questionnaire | [base]/StructureDefinition/[id]/$questionnaire
Value Set Expansion	[base]/ValueSet/$expand | [base]/ValueSet/[id]/$expand
Concept Look Up	[base]/ValueSet/$lookup
Value Set based Validation	[base]/ValueSet/$validate-code | [base]/ValueSet/[id]/$validate-code
Batch Mode Validation	[base]/ValueSet/$batch

Notes:

• The special operations on the meta element also operate on previous version (/_history/) - they are the only ones

2.2.0.2 Implementations Defined Operations

Implementations are able to define their own operations in addition to those defined here. Name clashes between operations defined by different implementers can be resolved by use of the conformance statement.

In addition, the definition of these operations or additional run time operations does not prevent the use of other kinds of operations that are not dependent on and/or not integrated with the RESTful API, as long as their addressing scheme does not clash with the scheme defined herein.

2.2.0.3 Defining an Operation

Each Operation is defined by:

• A context for the operation - system, resource type, or resource instance
• A name for the operation
• A list of parameters, with their definitions

For each parameter, the following information is needed:

• Name - the name of the operation. For implementer convenience, the name should be a valid token (see below)
• Use - In | Out | Both
• Type - a data type or a resource type
• Profile - a profile that applies additional restrictions about the resource
• Documentation - describes its use

There is a special parameter type called "Tuple" which is a parameter type that has additional parts. Each part has the same information as a parameter, except for use, which is taken from the parameter it is part of.

The resource Operation Definition is used to provide a computable definition of the operation.

2.2.0.4 Extending an Operation

Implementations are able to extend operations by defining new named parameters. Implementations can publish their own extended definitions using the Operation Definition resource, and this variant definition can use OperationDefinition.base to refer to the underlying definition.

Note that the FHIR specification will never define any parameter names starting with "x-".

2.2.0.5 Executing an Operation Synchronously

Most commonly, operations are executed synchronously - the client sends a request to the server with the operation in parameters, and the server replies with the operation out parameters.

The URL for an operation end-point depends on its context:

• system: the url is [base]/$[name]
• resource type: the url is [base]/[type]/$[name]
• resource instance: the url is [base]/[type]/[id]/$[name]

2.2.0.5.1 Operation Request

In the general case, an operation is invoked by performing an HTTP POST to the operation end-point. The format of the submitted content is the special Parameters format - a list of named parameters (the "in" parameters). For an example, see the value set expansion request example.

Note that the same arrangement as the RESTful interface applies in regard to content types.

If there are no parameters with complex types (including resources) to the operation, and the operation is idempotent (see HTTP specification definition of idempotent), the operation may be invoked by performing an HTTP GET operation where all the parameters are appended to the URL in the search portion of the URL (e.g. after the "?"). Servers SHALL support this method of invocation.

Servers MAY choose to support submission of the parameters multi-part form method as well, which can be useful for allowing testing of an operation using HTML forms.

2.2.0.5.2 Operation Response

If the operation succeeds, the HTTP Status code is 200 OK. An HTTP status code if 4xx or 5xx indicates an error, and an OperationOutcome may be returned. User agents should note that servers may issue redirects etc to authenticate the client in response to an operation request.

In the general case, an operation response uses the same Parameters format one or more named parameters (the "out" parameters).

If there is only one out parameter, which is a resource, and it has the name "return" then the parameter format is not used, and the response is simply the resource itself.

The resources that are returned by the operation may be retained and made available in the resource repository on the operation server. In that case, the server will provide the identity of the resource in the returned resources. When resources that are not persisted are returned in the response, they will have no id property.

2.2.0.6 Executing an Operation Asynchronously

Operations can also be executed asynchronously. In this case, the requester sends a message requesting that an operation be executed, and the destination system subsequently sends a message back with the results of the operation.

Given the increased complexity of the asynchronous use case, the implementation has increased complexity. As a summary, asynchronous operations are performed like this:

• The requester contructs a message (a bundle with type = message)
• The message header has an event.system of http://blame-Lloyd.com/operations
• The event.code is the URL of the operation definition
• The message data item refers to a Parameters format that carries the in parameters for the operation. If there are no parameters, the message SHOULD have no data element
• The sender accepts the message (see Asynchronous messaging)
• When the operation has been executed, the processor sends back one or more messages
• Each message is a bundle of type = message that contains a message header that refers to the id of the original message
• If the operation fails, the MessageHeader.response.code must indicate failure, and an OperationOutcome SHOULD be returned as well
• If there is only one out parameter, which is a resource, and it has the name "return", then the data of the message is the return resource
• Else the message data will refer to a Parameters format that carries the out parameters for the operation. If there are no parameters, the message SHOULD have no data element

Todo: fill out with details and examples.