DSTU2 QA Preview
This page is part of the FHIR Specification (v1.0.0: DSTU 2 Ballot 3). 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
| FHIR Infrastructure Work Group | Maturity Level: N/A | Ballot Status: DSTU 2 |
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 (Execute). Operations are used where the server needs to play an active role in formulating the content of the response, not merely return existing information, or where the intended purpose is to cause side effects - modification of existing resources, or creation of new resourcse. This specification describes a light operation framework that seamlessly extends the RESTful API.
Operations have the following general properties:
Operations are (mostly) POSTs to a FHIR endpoint, where the name of the operations is prefixed by a “$” sign. For example:
POST http://fhir.someserver.org/fhir/Patient/1/$everything
Whenever the 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 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. In addition it may include strings that are formatted as the search parameter types.
On completion, the operation returns another Parameters resource, this time 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 - ones with simple input types and a single output parameter named 'return' that is a resource - can be invoked differently, by 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.
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 |
| 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 | |
| guidance | [base]/$guidance |
| guidanceRequirements | [base]/$guidance-requirements |
Notes:
meta element also operate on previous version (/_history/) - they are the only onesImplementations 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 here.
Each Operation is defined by:
For each parameter, the following information is needed:
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.
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-".
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:
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.
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 whether there is 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.
DSTU Note: there is no defined correct way to execute operations asynchronously. The messaging page describes a way to execute operations asynchronously using messages.
Feedback/discussion here
© HL7.org 2011+. FHIR DSTU2 (v1.0.0-6850) generated on Tue, Sep 1, 2015 14:42+1000.
Links: What's a DSTU? |
Version History |
Table of Contents |
Compare to DSTU1 |
|
Propose a change