This page is part of the FHIR Specification (v1.2.0: STU 3 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

2.2.0 Extended Operations on the RESTful API

FHIR Infrastructure Work Group

Maturity Level: N/A

Ballot Status: DSTU 2

The RESTful API defines a set of common interactions (read, update, search, etc.) performed on a repository of typed resources. 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 (Execute). Operations are used (a) where the server needs to play an active role in formulating the content of the response, not merely return existing information, or (b)where the intended purpose is to cause side effects such as the modification of existing resources, or creation of new resources. This specification describes a lightweight 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
• Parameters are either resources, data types or search parameters
• Operations are subject to the same security constraints and requirements as the RESTful API
• The URIs for the operation end-points are based on the existing RESTful API address scheme
• Operations may make use of the existing repository of resources in their definitions
• Operations may be performed on a specific resource, a resource type, or a whole system

2.2.0.1 Executing an Operation

Most Operations are a POST to a FHIR endpoint, where the name of the operations is prefixed by a "dollar sign" ('$') character. For example:

 POST http://fhir.someserver.org/fhir/Patient/1/$everything

When an operation is idempotent, and the parameters are all simple ones (as is the case with the example above), it may be invoked using GET as well.

Operations can be invoked on four types of FHIR endpoints:

• The "base" FHIR service endpoint (e.g. http://fhir.someserver.org/fhir): These are operations that operate on the full scale of the server. For example, "return me all extensions known by this server"
• A Resource type (e.g. http://fhir.someserver.org/fhir/Patient): These are operations that operate across all instances of a given resource type
• A Resource instance (e.g. http://fhir.someserver.org/fhir/Patient/1): These are operations involve only a single instance of a Resource, like the $everything operation above does
• A specific version of a resource instance (http://fhir.someserver.org/fhir/Patient/1/_history/4): These operations involve only a specific version of a single instance of a FHIR Resource and extists only to allow manipulation of profile and tag metadata of past versions

The body of the invocation contains a special infrastructure resource called Parameters, which represents a collection of named parameters as <key,value> pairs, where the value may be any primitive or complex datatype or even a full Resource. It may also include strings formatted as search parameter types.

Upon completion, the operation returns another Parameters resource, containing one or more output parameters. This means that a FHIR operation can take any parameter in and return a set of result parameters out. Both the body of the POST and the returned result are always a Resource.

Some Operations with simple input types and a single Resource output parameter named 'return' can be invoked using a GET directly, with parameters as HTTP URL parameters. In this case, the response is simply the resource that is the return value, with no Parameters resource.

2.2.0.2 FHIR defined Operations

This specification defines several operations:

Base Operations (All resource types)
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
Operations Defined by Resource Types
Generate a Document	[base]/Composition/$document
Concept Translation	[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate
Closure Table Maintenance	[base]/$closure
Evaluate	[base]/DecisionSupportRule/[id]/$evaluate
Evaluate	[base]/DecisionSupportServiceModule/[id]/$evaluate
Fetch Encounter Record	[base]/Encounter/[id]/$everything
Find a functional list	[base]/List/$find
Process Message	[base]/$process-message
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
Operations Defined by Implementation Guides

Notes:

• The special operations on the meta element also operate on previous versions of a resource (/_history/). They are the only operations that can manipulate versions other than the "current" version.

2.2.0.3 Implementation 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 the use of the server's Conformance statement.

Also, the definition of these 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, provided that their addressing scheme does not clash with the scheme defined here.

2.2.0.4 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 along with their definitions

For each parameter, the following information is needed:

• Name - the name of the parameter. 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 StructureDefinition that applies additional restrictions about the resource
• Documentation - a description of the parameter's 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.5 Extending an Operation

Implementations are able to extend an operation 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.6 Executing an Operation Synchronously

Operations are typically executed synchronously: a client sends a request to a server that includes the operation's 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.6.1 Operation Request

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

Note that the same arrangement as for the RESTful interface applies with respect 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 of the parameters are appended to the URL in the search portion of the URL (e.g. after the '?' character). Servers SHALL support this method of invocation.

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

2.2.0.6.2 Operation Response

If an operation succeeds, an HTTP Status code of 200 OK is retruned. An HTTP status code of 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 general, an operation response uses the same Parameters format whether there is only one or there are multiple named out parameters.

If there is only one out parameter, which is a Resource with the parameter 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 a response, they will have no id property.

2.2.0.7 Executing an Operation Asynchronously

DSTU Note: there is presentlly no mechanism to execute operations asynchronously in a RESTful manner. However, the messaging page describes a way to execute operations asynchronously using messages.

Provide feedback/discussion here .