This page is part of the FHIR Specification (v1.4.0:
STU
3 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
|
|
|
|
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
(
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
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
xecute). 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:
POST http://fhir.someserver.org/fhir/Patient/1/$everythingWhen 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
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 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
, 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
resource,
containing
one
or
more
output
parameters.
This
means
that
a
FHIR
operation
can
take
any
parameter
and
return
a
set
of
result
parameters
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
simple
input
types
and
a
single
Resource
output
parameter
named
'
. 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.
' 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.
This specification defines several operations:
|
|
|
|
|
|
|
|
|
|
|
[base]/[Resource]/[id]/$meta-add |
|
|
[base]/[Resource]/[id]/$meta-delete |
| The CDS Hook operation is the core API request for CDS Hooks | [base]/$cds-hook |
|
|
|
| Concept Look Up | [base]/CodeSystem/$lookup |
|
|
|
|
|
|
|
|
[base]/$closure |
| Evaluate | [base]/DecisionSupportRule/[id]/$evaluate |
| Evaluate | [base]/DecisionSupportServiceModule/[id]/$evaluate |
|
|
[base]/Encounter/[id]/$everything |
|
|
[base]/List/$find |
| Evaluate Measure | [base]/Measure/$evaluate-measure | [base]/Measure/[id]/$evaluate-measure |
|
|
[base]/$process-message |
| Place | [base]/OrderSet/[id]/$place |
| Find patient matches using MPI based logic | [base]/Patient/$match |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Fail Task | [base]/Task/[id]/$fail |
| Release Task | [base]/Task/[id]/$release |
| Suspend Task | [base]/Task/[id]/$suspend |
| Resume Task | [base]/Task/[id]/$resume |
| Cancel Task | [base]/Task/[id]/$cancel |
| Stop Task | [base]/Task/[id]/$stop |
| Set Task Input | [base]/Task/[id]/$set-input |
| Set Task Output | [base]/Task/[id]/$set-output |
| Value Set Expansion | [base]/ValueSet/$expand | [base]/ValueSet/[id]/$expand |
| Value Set based Validation | [base]/ValueSet/$validate-code | [base]/ValueSet/[id]/$validate-code |
|
|
|
Notes:
meta
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.
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 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'
parameters and the server replies with the operation's
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]
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
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
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 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
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
), 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.
If the only parameter to the operation is a resource, then the operation can also executed by a POST with that parameter as the body of the request.
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.
method as well, which can be useful when testing an operation using HTML forms.
If an operation succeeds, an HTTP Status code of 200 OK is returned. 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
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
format whether there is only one or there are multiple named
out
parameters.
If
there
is
only
one
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
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
id
property. property.
DSTU 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
. © HL7.org 2011+. FHIR DSTU2 (v1.0.2-7202) generated on Sat, Oct 24, 2015 07:44+1100. Links: Search.
© HL7.org 2011+. FHIR STU3 Candidate (v1.4.0-8139) generated on Thu, Mar 31, 2016 08:10+1100.
QA Page
Links:
Search
|
Version
History
|
Table
of
Contents
|
Compare
to
DSTU1
|
Version History
|
Table of Contents
|
Compare to DSTU2
|
|
|
Propose
a
change
|
Propose a change