Release
4
5
Exchange
This
page
is
part
of
the
FHIR
Specification
(v4.0.1:
R4
(v5.0.0:
R5
-
Mixed
Normative
and
STU
)
).
This
is
the
current
published
version
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
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 : Normative | Standards Status : Normative |
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 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 where:
such
as
the
modification
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 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
datatypes
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
three
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. A FHIR operation can take a set of zero or more input parameters; in the case where there is zero parameters, the resource may be omitted, and the body will be empty (see below).
Upon
completion,
the
operation
returns
an
HTTP
status
code
indicating
what
the
outcome
of
performing
the
operation,
and
optionally
another
Parameters
resource,
containing
one
ne
or
more
output
parameters.
This
means
that
If
there
is
a
FHIR
operation
can
take
single
output
parameter
named
'return'
with
a
set
maximum
cardinality
of
zero
or
more
parameters
in
and
return
1,
with
a
set
of
type
corresponding
to
a
resource,
then
the
response
SHALL
be
the
resource
that
is
the
return
value,
with
no
wrapping
Parameters
resource.
If
there
is
zero
or
more
result
output
parameters
out
.
(possibly
because
the
operation
failed),
then
the
resource
can
be
omitted,
and
the
body
will
be
empty.
Both
the
body
of
the
POST
and
the
returned
result
are
always
a
Resource.
Resource
if
any
body
is
present,
except
in
the
case
that
the
server
supports
multi-part/form-data
(see
below).
Operations
may
be
invoked
using
a
GET
,
with
parameters
as
HTTP
URL
parameters,
if:
If
there
is
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
will
typically
be
'
collection
',
unless
though
it
could
be
one
of
the
other
types.
For
eample,
if
the
operation
has
search
semantics
,
such
as
matching
resource
counts,
and
page
links
(next
etc)
etc.)
then
the
Bundle.type
will
typically
be
'
search-set
'
.
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. See additional discussion in Derived OperationDefinitions
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
has
affectsState
=
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
If
an
operation
has
exactly
one
input
parameter
of
whose
type
is
a
FHIR
Resource
(irrespective
of
whether
and
all
other
possible
parameters
a
client
intends
to
submit
are
defined),
that
simple
parameters
,
then
the
client
MAY
invoke
the
operation
can
also
be
executed
by
a
via
POST
with
that
the
input
resource
as
the
body
of
the
request
(and
no
body
and
additional
parameters
on
as
query
parameters.
Servers
SHALL
support
this
means
of
invocation
of
the
url).
operation.
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. Servers SHALL return the appropriate status code. 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 single 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.
FHIR
®©
HL7.org
2011+.
FHIR
Release
4
(Technical
Correction
#1)
(v4.0.1)
R5
hl7.fhir.core#5.0.0
generated
on
Fri,
Nov
1,
2019
09:37+1100.
QA
Page
Sun,
Mar
26,
2023
15:26+1100.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
Glossary
|
QA
|
Compare
to
R3
R4
|
Compare
to
R4B
|
|
Propose
a
change