|FHIR Infrastructure Work Group||Maturity Level: 5||Ballot Status: Trial Use|
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:
Operations are executed using a URL derived from the FHIR endpoint, where the name of the operations is prefixed by a "dollar sign" ('$') character. For example:
When an operation is idempotent, and the parameters are all primitive data types with no extensions (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 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 a set of zero or more parameters in and return a set of zero or more
result parameters out. Both the body of the POST and the returned result are always a Resource.
Some Operations with primitive 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. These kinds of usage are discussed further below.
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 Capability 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.
Each Operation is defined by:
For each parameter, the following information is needed:
Parameters may be nested into multi-part parameters. 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.
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-".
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's out parameters.
The URL for an operation end-point depends on its context:
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 when parameters have a search type, the search modifiers are available, and are used on the parameter name in the Parameters resource (e.g. "code:in").
Note that the same arrangement as for the RESTful interface applies with respect to content types.
If all the parameters for the operation are primitive types, 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 values 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. E.g.
When using the HTTP GET operation, if there is a repeating parameter for the extended operation the values for that parameter are repeated by repeating the named parameter. E.g. Observation $stats statistic parameter
If the only parameter to a specific invocation of the operation is a resource, then the operation can also be executed by a POST with that resource as the body of the request.
Servers MAY choose to support submission of the parameters represented in multi-part/form-data format as well, which can be useful when testing an operation using HTML forms.
If an operation succeeds, an HTTP Status success code is returned. This will usually be a 2xx code, though it may also be a 303 See Other. Other kinds of 3xx codes should be understood to indicate that the operation did not proceed, and the client will need to re-issue the operation if it can perform the redirection (e.g. may get redirected to an authentication step). User agents should note that servers may issue redirects, etc. to authenticate the client in response to an operation request. An HTTP status code of 4xx or 5xx indicates an error, and an OperationOutcome SHOULD be returned with details.
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 response,
they will have no
STU Note: there is presently 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 .