mirror of
https://github.com/hapifhir/hapi-fhir.git
synced 2025-03-09 14:33:32 +00:00
1380 lines
44 KiB
XML
1380 lines
44 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
|
|
|
|
<properties>
|
|
<title>RESTful Operations - HAPI FHIR</title>
|
|
<author email="jamesagnew@users.sourceforge.net">James Agnew</author>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Implementing Resource Provider Operations">
|
|
|
|
<p>
|
|
Jump To...
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<a href="#operations">Operations</a>
|
|
</li>
|
|
<li>
|
|
<a href="#exceptions">Exceptions</a>
|
|
</li>
|
|
<li>
|
|
<a href="#tags">Tags</a>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
RESTful Clients and Servers both share the same
|
|
method pattern, with one key difference: A client
|
|
is defined using annotated methods on an interface
|
|
which are used to retrieve
|
|
resources,
|
|
whereas a server requires concrete method
|
|
implementations
|
|
to actually provide those resources.
|
|
</p>
|
|
|
|
<p>
|
|
Unless otherwise specified, the examples below show
|
|
<b>server</b>
|
|
implementations, but client methods will follow the same patterns.
|
|
</p>
|
|
|
|
<a name="operations" />
|
|
</section>
|
|
|
|
<section name="Operations">
|
|
<p>
|
|
The following table lists the operations supported by
|
|
HAPI FHIR RESTful Servers and Clients.
|
|
</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr style="font-weight: bold; font-size: 1.2em;">
|
|
<td>Operation</td>
|
|
<td>Definition</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<a href="#instance_read">Instance - Read</a>
|
|
</td>
|
|
<td>
|
|
Read the current state of the resource
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#instance_vread">Instance - VRead</a>
|
|
</td>
|
|
<td>
|
|
Read the state of a specific version of the resource
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#instance_update">Instance - Update</a>
|
|
</td>
|
|
<td>
|
|
Read the state of a specific version of the resource
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#instance_delete">Instance - Delete</a>
|
|
</td>
|
|
<td>
|
|
Delete a resource
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#history">Instance - History</a>
|
|
</td>
|
|
<td>
|
|
Retrieve the update history for a particular resource
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#type_create">Type - Create</a>
|
|
</td>
|
|
<td>
|
|
Create a new resource with a server assigned id
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#type_search">Type - Search</a>
|
|
<macro name="toc">
|
|
<param name="section" value="8" />
|
|
<param name="fromDepth" value="2" />
|
|
</macro>
|
|
</td>
|
|
<td>
|
|
Search the resource type based on some filter criteria
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#history">Type - History</a>
|
|
</td>
|
|
<td>
|
|
Retrieve the update history for a particular resource type
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#type_validate">Type - Validate</a>
|
|
</td>
|
|
<td>
|
|
Check that the content would be acceptable as an update
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#system_conformance">System - Conformance</a>
|
|
</td>
|
|
<td>
|
|
Get a conformance statement for the system
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#system_transaction">System - Transaction</a>
|
|
</td>
|
|
<td>
|
|
Update, create or delete a set of resources as a single transaction
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#history">System - History</a>
|
|
</td>
|
|
<td>
|
|
Retrieve the update history for all resources
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#system_search">System - Search</a>
|
|
</td>
|
|
<td>
|
|
Search across all resource types based on some filter criteria
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#tags">Tag Operations</a>
|
|
</td>
|
|
<td>
|
|
Search across all resource types based on some filter criteria
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
<a name="instance_read" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Instance Level - Read">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#read">
|
|
<b>read</b>
|
|
</a>
|
|
operation retrieves a resource by ID. It is annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/Read.html">@Read</a>
|
|
annotation, and has a single parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/IdParam.html">@IdParam</a>
|
|
annotation.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="read" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient/111</code>
|
|
</p>
|
|
|
|
<p>
|
|
The following snippet shows how to define a client interface
|
|
to handle a read method.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="clientReadInterface" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<a name="instance_vread" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Instance Level - VRead">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#vread">
|
|
<b>vread</b>
|
|
</a>
|
|
operation retrieves a specific version of a resource with a given ID.
|
|
To support vread, simply add "version=true" to your @Read annotation. This
|
|
means that the read method will support both "Read" and "VRead". The IdDt
|
|
may or may not have the version populated depending on the client request.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="vread" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient/111/_history/2</code>
|
|
</p>
|
|
|
|
<a name="instance_update" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Instance Level - Update">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#update">
|
|
<b>update</b>
|
|
</a>
|
|
operation updates a specific resource instance (using its ID), and optionally
|
|
accepts a version ID as well (which can be used to detect version conflicts).
|
|
</p>
|
|
<p>
|
|
Update methods must be annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/Update.html">@Update</a>
|
|
annotation, and have a parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/ResourceParam.html">@Resource</a>
|
|
annotation. This parameter contains the resource instance to be created.
|
|
</p>
|
|
<p>
|
|
In addition, the method must have a parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/IdParam.html">@IdParam</a>
|
|
annotation, and optionally may have a parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/VersionIdParam.html">@VersionIdParam</a>
|
|
</p>
|
|
<p>
|
|
Update methods must return an object of type
|
|
<a href="./apidocs/ca/uhn/fhir/rest/api/MethodOutcome.html">MethodOutcome</a>
|
|
. This
|
|
object contains the identity of the created resource.
|
|
</p>
|
|
<p>
|
|
The following snippet shows how to define an update method on a server:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="update" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method (this would be invoked using an HTTP PUT,
|
|
with the resource in the PUT body):
|
|
<br />
|
|
<code>http://fhir.example.com/Patient</code>
|
|
</p>
|
|
|
|
<p>
|
|
The following snippet shows how the corresponding client interface
|
|
would look:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="updateClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
In the case of a server which is able to do version conflict checking, an
|
|
extra parameter would be added:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="updateVersion" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<a name="instance_delete" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Instance Level - Delete">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#delete">
|
|
<b>delete</b>
|
|
</a>
|
|
operation retrieves a specific version of a resource with a given ID. It takes a single
|
|
ID parameter annotated with an
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/IdParam.html">@IdParam</a>
|
|
annotation, which supplies the ID of the resource to delete.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="delete" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Delete methods are allowed to return the following types:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b>void</b>
|
|
: This method may return
|
|
<code>void</code>
|
|
, in which case
|
|
the server will return an empty response and the client will ignore
|
|
any successful response from the server (failure responses will still throw
|
|
an exception)
|
|
</li>
|
|
<li>
|
|
<b>
|
|
<a href="./apidocs/ca/uhn/fhir/rest/api/MethodOutcome.html">MethodOutcome</a>
|
|
</b>
|
|
:
|
|
This method may return
|
|
<code>MethodOutcome</code>
|
|
,
|
|
which is a wrapper for the FHIR OperationOutcome resource, which may optionally be returned
|
|
by the server according to the FHIR specification.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Example URL to invoke this method (HTTP DELETE):
|
|
<br />
|
|
<code>http://fhir.example.com/Patient/111</code>
|
|
</p>
|
|
|
|
<a name="type_create" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Type Level - Create">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#create">
|
|
<b>create</b>
|
|
</a>
|
|
operation saves a new resource to the server, allowing the server to
|
|
give that resource an ID and version ID.
|
|
</p>
|
|
<p>
|
|
Create methods must be annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/Create.html">@Create</a>
|
|
annotation, and have a single parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/ResourceParam.html">@Resource</a>
|
|
annotation. This parameter contains the resource instance to be created.
|
|
</p>
|
|
<p>
|
|
Create methods must return an object of type
|
|
<a href="./apidocs/ca/uhn/fhir/rest/api/MethodOutcome.html">MethodOutcome</a>
|
|
. This
|
|
object contains the identity of the created resource.
|
|
</p>
|
|
<p>
|
|
The following snippet shows how to define a server create method:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="create" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method (this would be invoked using an HTTP POST,
|
|
with the resource in the POST body):
|
|
<br />
|
|
<code>http://fhir.example.com/Patient</code>
|
|
</p>
|
|
|
|
<p>
|
|
The following snippet shows how the corresponding client interface
|
|
would look:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="createClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<a name="type_search" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Type Level - Search">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#search">
|
|
<b>search</b>
|
|
</a>
|
|
operation returns a bundle
|
|
with zero-to-many resources of a given type, matching a given set of parameters.
|
|
</p>
|
|
|
|
<subsection name="Search with No Parameters">
|
|
|
|
<p>
|
|
The following example shows a search with no parameters. This operation
|
|
should return all resources of a given type (this obviously doesn't make
|
|
sense in all contexts, but
|
|
does for some resource types).
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchAll" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
<subsection name="Search Parameters: Introduction (String)">
|
|
|
|
<p>
|
|
To allow a search using given search parameters, add one or more parameters
|
|
to your search method and tag these parameters as either
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/parameters/RequiredParam.html">@RequiredParam</a>
|
|
or
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/parameters/OptionalParam.html">@OptionalParam</a>
|
|
.
|
|
</p>
|
|
|
|
<p>
|
|
This annotation takes a "name" parameter which specifies the parameter's
|
|
name (as it will appear in the search URL). FHIR defines standardized parameter
|
|
names for each
|
|
resource, and these are available as constants on the
|
|
individual HAPI resource
|
|
classes.
|
|
</p>
|
|
|
|
<p>
|
|
Parameters which take a string as their format should use the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/param/StringParameter.html">StringParameter</a>
|
|
type. They may also use normal java Strings (or HAPI's StringDt), although it is
|
|
not possible to use the ":exact" qualifier in that case.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchStringParam" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?family=SMITH</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
<subsection name="Search Parameters: Token/Identifier">
|
|
|
|
<p>
|
|
Searches method parameters may be of any type that implements the
|
|
<a href="./apidocs/ca/uhn/fhir/model/api/IQueryParameterType.html">IQueryParameterType</a>
|
|
interface.
|
|
</p>
|
|
<p>
|
|
The "token" type is used for parameters which have two parts, such as
|
|
an idnetifier (which has a system URI, as well as the actual identifier)
|
|
or a code (which has a code system, as well as the actual code).
|
|
For example, the search below can be used to search by
|
|
identifier (e.g. search for an MRN).
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchIdentifierParam" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?identifier=urn:foo|7000135</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Search Parameters: Date (Simple)">
|
|
|
|
<p>
|
|
The FHIR specification provides a sytax for specifying
|
|
dates (and date/times as well, but for simplicity we will just say dates here)
|
|
as search criteria.
|
|
</p>
|
|
|
|
<p>
|
|
Dates may be optionally prefixed with a qualifier. For example, the
|
|
string
|
|
<code>>=2011-01-02</code>
|
|
means any date on or after 2011-01-02.
|
|
</p>
|
|
|
|
<p>
|
|
To accept a qualified date parameter, use the
|
|
QualifiedDateParam
|
|
parameter type.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="dates" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Observation?birthdate=>=2011-01-02</code>
|
|
</p>
|
|
|
|
<p>
|
|
Invoking a client of thie type involves the following syntax:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="dateClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
</subsection>
|
|
|
|
<a name="DATE_RANGES" />
|
|
<subsection name="Search Parameters: Date (Ranges)">
|
|
|
|
<p>
|
|
A common scenario in searches is to allow searching for resources
|
|
with values (i.e timestamps) within a range of dates.
|
|
</p>
|
|
|
|
<p>
|
|
FHIR allows for multiple parameters with the same key, and interprets
|
|
these as being an "AND" set. So, for example, a range of
|
|
<br />
|
|
<code>DATE >= 2011-01-01</code>
|
|
and
|
|
<code>DATE < 2011-02-01</code>
|
|
<br />
|
|
can be interpreted as any date within January 2011.
|
|
</p>
|
|
|
|
<p>
|
|
The following snippet shows how to accept such a range, and combines it
|
|
with a specific identifier, which is a common scenario. (i.e. Give me a list
|
|
of observations for a
|
|
specific patient within a given date range)
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="dateRange" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Observation?subject.identifier=7000135&date=>=2011-01-01&date=<2011-02-01</code>
|
|
</p>
|
|
|
|
<p>
|
|
Invoking a client of this type involves the following syntax:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="dateClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<h4>Unbounded Ranges</h4>
|
|
|
|
<p>
|
|
Note that when using a date range parameter, it is also possible for
|
|
the client to request an "unbounded" range. In other words, a range that
|
|
only a start date and no end
|
|
date, or vice versa.
|
|
</p>
|
|
|
|
<p>
|
|
An example of this might be the following URL, which refers to any Observation
|
|
resources for the given MRN and having a date after 2011-01-01.
|
|
<br />
|
|
<code>http://fhir.example.com/Observation?subject.identifier=7000135&date=>=2011-01-01</code>
|
|
<br />
|
|
When such a request is made of a server (or to make such a request from a client),
|
|
the
|
|
<code>getLowerBound()</code>
|
|
or
|
|
<code>getUpperBound()</code>
|
|
property of the
|
|
<code>DateRangeParam</code>
|
|
object will be set to
|
|
<code>null</code>
|
|
.
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Search Parameters: Quantity">
|
|
|
|
<p>
|
|
Quantity parameters allow a number with units and a comparator
|
|
</p>
|
|
|
|
<p>
|
|
The following snippet shows how to accept such a range, and combines it
|
|
with a specific identifier, which is a common scenario. (i.e. Give me a list
|
|
of observations for a
|
|
specific patient within a given date range)
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="quantity" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Observation?value-quantity=<=123.2||mg</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Search Parameters: Resource Reference">
|
|
|
|
<p>
|
|
Many search parameters refer to resource references. For instance, the Patient
|
|
parameter "provider" refers to the resource marked as the managing organization
|
|
for patients.
|
|
</p>
|
|
<p>
|
|
Reference parameters use the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/param/ReferenceParam.html">ReferenceParam</a>
|
|
type. Reference param objects being passed into server methods will have three properties
|
|
populated:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b>The resource type (optional):</b> This is the type of resource
|
|
being targeted, if the client specifies one in the URL.
|
|
</li>
|
|
<li>
|
|
<b>The chain property (optional):</b> This is the name of the
|
|
property on the target resource to search for
|
|
</li>
|
|
<li>
|
|
<b>The value (required):</b> This is the actual value to search for. If
|
|
a chain property has not been specified, this is the ID of the resource.
|
|
</li>
|
|
</ul>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="reference" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URLs to invoke this method:
|
|
<br />
|
|
Resource by ID: <code>http://fhir.example.com/Patient?provider=1234</code>
|
|
<br />
|
|
Resource by chained parameter value: <code>http://fhir.example.com/Patient?provider:Organization.name=FooOrg</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Combining Multiple Parameters">
|
|
|
|
<p>
|
|
Search methods may take multiple parameters, and these parameters
|
|
may (or may not) be optional.
|
|
aaaa
|
|
To add a second required parameter, annotate the
|
|
parameter with
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/parameters/RequiredParam.html">@RequiredParam</a>
|
|
.
|
|
To add an optional parameter (which will be passed in as
|
|
<code>null</code>
|
|
if no value
|
|
is supplied), annotate the method with
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/parameters/OptionalParam.html">@OptionalParam</a>
|
|
.
|
|
</p>
|
|
|
|
<p>
|
|
You may annotate a method with any combination of as many @RequiredParam and as many @OptionalParam
|
|
parameters as you want. It is valid to have only @RequiredParam
|
|
parameters, or
|
|
only @OptionalParam parameters, or any combination of the two.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchOptionalParam" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URLs to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?family=SMITH</code>
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?family=SMITH&given=JOHN</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Composite (Multi-Valued) Parameters">
|
|
|
|
<p>
|
|
It is possible to accept multiple values of a single parameter
|
|
as well. This is useful in cases when you want to return a list
|
|
of resources with criteria matching a list of
|
|
possible values.
|
|
See the
|
|
<a href="http://www.hl7.org/implement/standards/fhir/search.html#combining">FHIR Specification</a>
|
|
for more information.
|
|
</p>
|
|
|
|
<p>
|
|
The FHIR specification allows two types of composite parameters:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Where a parameter may accept multiple comma separated values within a single value string
|
|
(e.g.
|
|
<code>?language=FR,NL</code>
|
|
) this is treated as an
|
|
<b>OR</b>
|
|
relationship, and
|
|
the search should return elements matching either one or the other.
|
|
</li>
|
|
<li>
|
|
Where a parameter may accept multiple value strings for the same parameter name
|
|
(e.g.
|
|
<code>?language=FR&language=NL</code>
|
|
) this is treated as an
|
|
<b>AND</b>
|
|
relationship,
|
|
and the search should return only elements matching both.
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>OR Relationship Query Parameters</h4>
|
|
|
|
<p>
|
|
To accept a composite parameter, use a parameter type which implements the
|
|
<a href="./apidocs/ca/uhn/fhir/model/api/IQueryParameterOr.html">IQueryParameterOr</a>
|
|
interface. For example, to accept searches for
|
|
Observations matching any of a collection of names:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchMultiple" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Observation?name=urn:fakenames|123,urn:fakenames|456</code>
|
|
</p>
|
|
|
|
<h4>AND Relationship Query Parameters</h4>
|
|
|
|
<p>
|
|
To accept a composite parameter, use a parameter type which implements the
|
|
<a href="./apidocs/ca/uhn/fhir/model/api/IQueryParameterAnd.html">IQueryParameterAnd</a>
|
|
interface.
|
|
</p>
|
|
|
|
<p>
|
|
See the section below on
|
|
<a href="#DATE_RANGES">date ranges</a>
|
|
for
|
|
one example of an AND parameter.
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Resource Includes (_include)">
|
|
|
|
<p>
|
|
FHIR allows clients to request that specific linked resources be included
|
|
as contained resources, which means that they will be "embedded" in a special
|
|
container called
|
|
"contained" within the parent resource.
|
|
</p>
|
|
|
|
<p>
|
|
HAPI allows you to add a parameter for accepting includes if you wish
|
|
to support them for specific search methods.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="pathSpec" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/DiagnosticReport?subject.identifier=7000135&_include=DiagnosticReport.subject</code>
|
|
</p>
|
|
|
|
<p>
|
|
It is also possible to use a String type for the include parameter,
|
|
which is more convenient if only a single include (or null for none)
|
|
is all that is required.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="pathSpecSimple" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Named Queries (_query)">
|
|
|
|
<p>
|
|
FHIR supports
|
|
<a href="http://www.hl7.org/implement/standards/fhir/search.html#advanced">named queries</a>
|
|
,
|
|
which may have specific behaviour defined. The following example shows how to create a Search
|
|
operation with a name.
|
|
</p>
|
|
|
|
<p>
|
|
This operation can only be invoked by explicitly specifying the given query name
|
|
in the request URL. Note that the query does not need to take any parameters.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="searchNamedQuery" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?_query=namedQuery1&someparam=value</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Sorting (_sort)">
|
|
|
|
<p>
|
|
FHIR supports
|
|
<a href="http://www.hl7.org/implement/standards/fhir/search.html#sort">sorting</a>
|
|
according to a specific set of rules.
|
|
</p>
|
|
|
|
<p>
|
|
According to the specification, sorting is requested by the client using a
|
|
search param as the sort key. For example, when searching Patient resources,
|
|
a sort key of "given" requests the "given" search param as the sort key. That
|
|
param maps to the values in the field "Patient.name.given".
|
|
</p>
|
|
|
|
<p>
|
|
Sort specifications can be passed into handler methods by adding a parameter
|
|
of type
|
|
SortSpec,
|
|
which has been annotated with the
|
|
@Sort
|
|
annotation, as shown in the following example:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="sort" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>http://fhir.example.com/Patient?_identifier=urn:foo|123&_sort=given</code>
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
<a name="type_validate" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Type Level - Validate">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#validate">
|
|
<b>validate</b>
|
|
</a>
|
|
tests whether a resource passes business validation, and would be
|
|
acceptable for saving to a server (e.g. by a create or update method).
|
|
</p>
|
|
<p>
|
|
Validate methods must be annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/Validate.html">@Validate</a>
|
|
annotation, and have a parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/ResourceParam.html">@Resource</a>
|
|
annotation. This parameter contains the resource instance to be created.
|
|
</p>
|
|
<p>
|
|
Validate methods may optionally also have a parameter
|
|
oftype IdDt annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/IdParam.html">@IdParam</a>
|
|
annotation. This parameter contains the resource ID (see the
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#validation">FHIR specification</a>
|
|
for details on how this is used)
|
|
</p>
|
|
<p>
|
|
Validate methods must return normally if the resource validates successfully,
|
|
or throw an
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/exceptions/UnprocessableEntityException.html">UnprocessableEntityException</a>
|
|
or
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/exceptions/InvalidRequestException.html">InvalidRequestException</a>
|
|
if the validation fails.
|
|
</p>
|
|
<p>
|
|
Validate methods must return either:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b>void</b>
|
|
- The method should throw an exception for a validation failure, or return normally.
|
|
</li>
|
|
<li>
|
|
An object of type
|
|
<a href="./apidocs/ca/uhn/fhir/rest/api/MethodOutcome.html">MethodOutcome</a>
|
|
. The
|
|
MethodOutcome may optionally be populated with an OperationOutcome resource, which
|
|
will be returned to the client if it exists.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The following snippet shows how to define a server validate method:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="validate" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method (this would be invoked using an HTTP POST,
|
|
with the resource in the POST body):
|
|
<br />
|
|
<code>http://fhir.example.com/Patient/_validate</code>
|
|
</p>
|
|
|
|
<a name="system_conformance" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="System Level - Conformance">
|
|
|
|
<p>
|
|
FHIR defines that a FHIR Server must be able to export a conformance statement,
|
|
which is an instance of the
|
|
<a href="http://hl7.org/implement/standards/fhir/conformance.html">Conformance</a>
|
|
resource describing the server itself.
|
|
</p>
|
|
|
|
<p>
|
|
The HAPI FHIR RESTful server will automatically export such
|
|
a conformance statement. See the
|
|
<a href="./doc_rest_server.html">RESTful Server</a>
|
|
documentation for more information.
|
|
</p>
|
|
|
|
<p>
|
|
If you wish to override this default behaviour by creating
|
|
your own metadata provider, you simply need to define a class
|
|
with a method annotated using the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/Metadata.html">@Metadata</a>
|
|
annotation.
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="metadataProvider" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
To create a Client which can retrieve a Server's conformance
|
|
statement is simple. First, define your Client Interface, using
|
|
the @Metadata annotation:
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="metadataClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Then use the standard
|
|
<a href="doc_rest_client.html">RESTful Client</a>
|
|
mechanism for instantiating
|
|
a client:
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="metadataClientUsage" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<a name="system_transaction" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="System Level - Transaction">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#transaction">transaction</a>
|
|
action is among the most challenging parts of the FHIR specification to implement. It allows the
|
|
user to submit a bundle containing a number of resources to be created/updated/deleted as a single
|
|
atomic transaction.
|
|
</p>
|
|
|
|
<p>
|
|
HAPI provides a skeleton for implementing this action, although most of the effort
|
|
will depend on the underlying implementation. The following example shows
|
|
how to define a <i>transaction</i> method.
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="transaction" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
Example URL to invoke this method:
|
|
<br />
|
|
<code>POST http://fhir.example.com/</code><br/>
|
|
<i>(note that the content of this POST will be a bundle)</i>
|
|
</p>
|
|
|
|
|
|
<a name="system_search" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="System Level - Search">
|
|
|
|
<p>
|
|
Not yet implemented - Get in touch if you would like to help!
|
|
</p>
|
|
|
|
<a name="history" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="History (Instance, Type, Server)">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#history">
|
|
<b>history</b>
|
|
</a>
|
|
operation retrieves a historical collection of all versions of a single resource
|
|
<i>(instance history)</i>
|
|
, all resources of a given type
|
|
<i>(type history)</i>
|
|
,
|
|
or all resources of any type on a server
|
|
<i>(server history)</i>
|
|
.
|
|
</p>
|
|
<p>
|
|
History methods must be annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/History.html">@History</a>
|
|
annotation, and will have additional requirements depending on the kind
|
|
of history method intended:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
For an
|
|
<b>Instance History</b>
|
|
method, the method must have a parameter
|
|
annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/IdParam.html">@IdParam</a>
|
|
annotation, indicating the ID of the resource for which to return history.
|
|
<ul>
|
|
<li>
|
|
For a server
|
|
implementation, the method must either be defined in a
|
|
<a href="./doc_rest_server.html#resource_providers">resource provider</a>
|
|
or have a
|
|
<code>type()</code>
|
|
value in the @History annotation if it is
|
|
defined in a
|
|
<a href="./doc_rest_server.html#plain_providers">plain provider</a>
|
|
.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
For a
|
|
<b>Type History</b>
|
|
method, the method must not have any @IdParam parameter.
|
|
<ul>
|
|
<li>
|
|
For a server
|
|
implementation, the method must either be defined in a
|
|
<a href="./doc_rest_server.html#resource_providers">resource provider</a>
|
|
or have a
|
|
<code>type()</code>
|
|
value in the @History annotation if it is
|
|
defined in a
|
|
<a href="./doc_rest_server.html#plain_providers">plain provider</a>
|
|
.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
For a
|
|
<b>Server History</b>
|
|
method, the method must not have any @IdParam parameter, and
|
|
must not have a
|
|
<code>type()</code>
|
|
value specified in
|
|
the @History annotation.
|
|
<ul>
|
|
<li>
|
|
In a server implementation, the method must
|
|
be defined in a
|
|
<a href="./doc_rest_server.html#plain_providers">plain provider</a>
|
|
.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The following snippet shows how to define a history method on a server:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="history" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
The following snippet shows how to define various history methods in a client.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="historyClient" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<a name="exceptions" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Exceptions">
|
|
|
|
<p>
|
|
When implementing a server operation, there are a number of failure conditions
|
|
specified. For example, an
|
|
<a href="#instance_read">Instance Read</a>
|
|
request might specify an unknown
|
|
resource ID, or a
|
|
<a href="#type_create">Type Create</a>
|
|
request might contain an
|
|
invalid resource which can not be created.
|
|
</p>
|
|
<p>
|
|
In these cases, an appropriate exception should be thrown. The HAPI RESTful
|
|
API includes a set of exceptions extending
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/exceptions/BaseServerResponseException.html">BaseServerResponseException</a>
|
|
which represent specific HTTP failure codes.
|
|
</p>
|
|
<p>
|
|
See the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/server/exceptions/package-summary.html">Exceptions List</a>
|
|
for a complete list of these exceptions. Note that these exceptions are all
|
|
<b>unchecked</b>
|
|
exceptions, so they do not need to ne explicitly declared in the method
|
|
signature.
|
|
</p>
|
|
|
|
<a name="tags" />
|
|
</section>
|
|
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
<!-- ****************************************************************** -->
|
|
|
|
<section name="Tags">
|
|
|
|
<p>
|
|
FHIR RESTful servers may support a feature known as tagging. Tags are a set of
|
|
named flags called "terms" (with an optional accompanying human friendly name
|
|
called a "label",
|
|
and an optional namespace called a "scheme").
|
|
</p>
|
|
<p>
|
|
Tags have very specific semantics, which may not be
|
|
obvious simply by using the HAPI API. It is important to review the specification
|
|
pages
|
|
<a href="http://hl7.org/implement/standards/fhir/http.html#tags">here</a>
|
|
and
|
|
<a href="http://hl7.org/implement/standards/fhir/extras.html#tags">here</a>
|
|
before attempting to implement tagging in your own applications.
|
|
</p>
|
|
|
|
<subsection name="Accessing Tags in a Read / VRead / Search Method">
|
|
|
|
<p>
|
|
Tags are stored within a resource object, in the
|
|
<a href="./apidocs/ca/uhn/fhir/model/api/IResource.html#getResourceMetadata()">IResource.html#getResourceMetadata()</a>
|
|
map, under the key
|
|
<a href="./apidocs/ca/uhn/fhir/model/api/ResourceMetadataKeyEnum.html#TAG_LIST">TAG_LIST</a>.
|
|
</p>
|
|
|
|
<p>
|
|
In a server implementation, you may populate your tags into the
|
|
returned resource(s) and HAPI will automatically place these tags into
|
|
the response headers (for read/vread) or the bundle category tags (for search).
|
|
The following example illustrates how to return tags from a server method. This
|
|
example shows how to supply tags in a read method, but the same approach applies
|
|
to vread and search operations as well.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="readTags" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
In a client operation, you simply call the read/vread/search method as you
|
|
normally would (as described above), and if any tags have been returned
|
|
by the server, these may be accessed from the resource metadata.
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="clientReadTags" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="Setting Tags in a Create/Update Method">
|
|
|
|
<p>
|
|
Within a <a href="#type_create">Type Create</a>
|
|
or <a href="#instance_update">Instance Update</a> method, it is
|
|
possible for the client to specify a set of tags to be stored
|
|
along with the saved resource instance.
|
|
</p>
|
|
<p>
|
|
Note that FHIR specifies that in an update method, any tags supplied
|
|
by the client are copied to the newly saved version, as well as any
|
|
tags the existing version had.
|
|
</p>
|
|
|
|
<p>
|
|
To work with tags in a create/update method, the pattern used in the
|
|
read examples above is simply revered. In a server, the resource which
|
|
is passed in will be populated with any tags that the client supplied:
|
|
</p>
|
|
|
|
<macro name="snippet">
|
|
<param name="id" value="createTags" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="More tag methods">
|
|
|
|
<p>
|
|
FHIR also provides a number of operations to interact directly
|
|
with tags. These methods may be used to retrieve lists of tags
|
|
that are available on the server, or to add or remove tags from
|
|
resources without interacting directly with those resources.
|
|
</p>
|
|
|
|
<p>
|
|
On a server these methods may be placed in a plain provider, or in a resource
|
|
provider in the case of resource type specific methods.
|
|
</p>
|
|
<macro name="snippet">
|
|
<param name="id" value="tagMethodProvider" />
|
|
<param name="file" value="src/site/example/java/example/RestfulPatientResourceProviderMore.java" />
|
|
</macro>
|
|
|
|
<p>
|
|
On a client, the methods are defined in the exact same way, except that
|
|
there is no method body in the client interface.
|
|
</p>
|
|
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
</body>
|
|
|
|
</document>
|