<del class="diff-old">
This
page
is
part
of
the
FHIR
Specification
(v0.0.82:
DSTU
1).
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
2.2.0
Extended
Operations
on
the
RESTful
API
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.
This
specification
describes
a
light
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
The
parameters
are
either
resources,
data
types
or
search
parameters
The
operations
are
subject
to
the
same
security
arrangements
as
the
RESTful
API
The
URIs
for
the
operation
end
points
are
based
on
the
existing
RESTful
API
address
scheme
The
operations
may
make
use
of
the
existing
repository
of
resources
in
their
definitions
Operations
are
performed
against
a
specific
resource,
a
resource
type,
or
the
whole
system
2.2.0.1
FHIR
defined
Operations
This
specification
defines
several
operations:
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
Generate
a
Document
[base]/Composition/$document
Concept
Translation
[base]/ConceptMap/$translate
|
[base]/ConceptMap/[id]/$translate
Batch
Mode
Translation
[base]/ConceptMap/$batch
Closure
Table
Maintenance
[base]/$closure
Fetch
Encounter
Record
[base]/Encounter/[id]/$everything
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
Batch
Mode
Validation
[base]/ValueSet/$batch
Notes:
The
special
operations
on
the
meta
element
also
operate
on
previous
version
(/_history/)
-
they
are
the
only
ones
2.2.0.2
Implementations
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
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
herein.
2.2.0.3
Defining
an
Operation
Each
Operation
is
defined
by:
A
context
for
the
operation
-
system,
resource
type,
or
resource
instance
A
name
for
the
operation
A
list
of
parameters,
with
their
definitions
For
each
parameter,
the
following
information
is
needed:
Name
-
the
name
of
the
operation.
For
implementer
convenience,
the
name
should
be
a
valid
token
(see
below)
Use
-
In
|
Out
|
Both
Type
-
a
data
type
or
a
resource
type
Profile
-
a
profile
that
applies
additional
restrictions
about
the
resource
Documentation
-
describes
its
use
There
is
a
special
parameter
type
called
&quot;Tuple&quot;
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.
2.2.0.4
Extending
an
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
&quot;x-&quot;.
2.2.0.5
Executing
an
Operation
Synchronously
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:
system:
the
url
is
[base]/$[name]
resource
type:
the
url
is
[base]/[type]/$[name]
resource
instance:
the
url
is
[base]/[type]/[id]/$[name]
2.2.0.5.1
Operation
Request
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
&quot;in&quot;
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
&quot;?&quot;).
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.
2.2.0.5.2
Operation
Response
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
one
or
more
named
parameters
(the
&quot;out&quot;
parameters).
If
there
is
only
one
out
parameter,
which
is
a
resource,
and
it
has
the
name
&quot;return&quot;
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.
2.2.0.6
Executing
an
Operation
Asynchronously
Operations
can
also
be
executed
asynchronously.
In
this
case,
the
requester
sends
a
message
requesting
that
an
operation
be
executed,
and
the
destination
system
subsequently
sends
a
message
back
with
the
results
of
the
operation.
Given
the
increased
complexity
of
the
asynchronous
use
case,
the
implementation
has
increased
complexity.
As
a
summary,
asynchronous
operations
are
performed
like
this:
The
requester
contructs
a
message
(a
bundle
with
type
=
message)
The
message
header
has
an
event.system
of
http://blame-Lloyd.com/operations
The
event.code
is
the
URL
of
the
operation
definition
The
message
data
item
refers
to
a
Parameters
format
that
carries
the
in
parameters
for
the
operation.
If
there
are
no
parameters,
the
message
SHOULD
have
no
data
element
The
sender
accepts
the
message
(see
Asynchronous
messaging
)
When
the
operation
has
been
executed,
the
processor
sends
back
one
or
more
messages
Each
message
is
a
bundle
of
type
=
message
that
contains
a
message
header
that
refers
to
the
id
of
the
original
message
If
the
operation
fails,
the
MessageHeader.response.code
must
indicate
failure,
and
an
OperationOutcome
SHOULD
be
returned
as
well
If
there
is
only
one
out
parameter,
which
is
a
resource,
and
it
has
the
name
&quot;return&quot;,
then
the
data
of
the
message
is
the
return
resource
Else
the
message
data
will
refer
to
a
Parameters
format
that
carries
the
out
parameters
for
the
operation.
If
there
are
no
parameters,
the
message
SHOULD
have
no
data
element
Todo:
fill
out
with
details
and
examples.
©
HL7.org
2011+.
FHIR
DSTU
(v0.4.0-4902)
generated
on
Fri,
Mar
27,
2015
00:23+1100.
Links:
What's
a
DSTU?
|
Version
History
|
Specification
Map
|
Compare
to
DSTU1
|
|
Propose
a
change
</del>