mirror of
https://github.com/hapifhir/hapi-fhir.git
synced 2025-03-09 14:33:32 +00:00
1073 lines
34 KiB
XML
1073 lines
34 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>
|
|
</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_search">Type - Create</a>
|
|
</td>
|
|
<td>
|
|
Create a new resource with a server assigned id
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<a href="#instance_update">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>
|
|
|
|
</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>
|
|
|
|
<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. It looks exactly
|
|
like a "read" operation, but with a second
|
|
parameter annotated with the
|
|
<a href="./apidocs/ca/uhn/fhir/rest/annotation/VersionIdParam.html">@VersionIdParam</a>
|
|
annotation.
|
|
</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>
|
|
|
|
<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="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>
|
|
|
|
<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>
|
|
Not yet implemented - Get in touch if you would like to help!
|
|
</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>
|
|
|
|
</section>
|
|
|
|
</body>
|
|
|
|
</document>
|