Exchange
FHIR
Infrastructure
Work
Group
| Maturity Level : 5 | Ballot Status : Normative |
Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package . Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.
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
C
reate/
R
ead/
U
pdate/
D
elete
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
(
E
xecute).
Operations
are
appropriately
used
(a)
where
where:
This specification describes a lightweight operation framework that seamlessly extends the RESTful API. The framework covers both how to execute such an operation (this page) and how to define an operation .
Operations have the following general properties:
Operations
are
executed
using
a
URL
derived
from
the
FHIR
endpoint,
where
the
name
of
the
operations
operation
is
prefixed
by
a
"dollar
sign"
('$')
character.
For
example:
POST http://fhir.someserver.org/fhir/Patient/1/$everything
When an operation has affectsState = false, 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. (Note: A HEAD request can also be used - see Support for HEAD ).
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
may
be
invoked
using
a
GET
,
with
parameters
as
HTTP
URL
directly,
parameters.
In
this
case,
parameters,
if:
If
there
is
simply
a
single
output
parameter
named
'return'
then
the
response
MAY
be
the
resource
that
is
the
return
value,
with
no
Parameters
resource.
These
kinds
of
usage
are
discussed
further
below.
If the response is a Bundle , the correct Bundle.type is ' collection ', unless it has search semantics , such as matching resource counts, and page links (next etc) .
Executing operations without any parameters is a special case. For an operation that doesn't cause any state change, the operation is invoked in a straight forward fashion:
GET [base]/Composition/example/$document
For operations that call state changes, they must be invoked by a POST. There is no parameters resource in this case because a parameters resource cannot be empty. So the operation is invoked with a POST with an empty body:
POST [base]/Claim/example/$submit Content-Length: 0
See the list of 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 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,
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
has
affectsState
=
false
(see
HTTP
specification
definition
of
idempotent
),
=
false,
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.
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/body-site&filter=abdo
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
GET [base]/Observation/$stats?subject=Patient/123&code=55284-4&system=http://loinc.org&duration=1&statistic=average&statistic=min&statistic=max&statistic=count
If, when invoking the operation, there is exactly one input parameter of type Resource (irrespective of whether other possible parameters are defined), that the operation can also be executed by a POST with that resource as the body of the request (and no parameters on the url).
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 result of an operation is subject to content negotiation like any other interaction . Specifically, if the returned resource is a Binary, the response SHALL behave in the same manner as if a 'read' operation had been performed on the resource. I.e. The content will be returned as either a FHIR resourse with base64-encoded content or as a raw binary, depending on the Accept header specified when invoking the operation (see Serving Binary Resources using the RESTful API ).
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.
Use the standard RESTful API Asynchronous pattern to execute operations asynchronously.
®©
HL7.org
2011+.
FHIR
Mixed
Nomative/Trial
Use
Ballot
(v3.3.0-13671)
Release
4
Candidate
(v3.6.0-5a1f92eb)
generated
on
Tue,
Apr
3,
Fri,
Oct
19,
2018
12:19+1000.
06:17+0000.
QA
Page
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
|
Compare
to
DSTU3
|
Ballot
Comparison
|
|
Propose
a
change