mirror of
https://github.com/hapifhir/hapi-fhir.git
synced 2025-03-09 14:33:32 +00:00
425 lines
15 KiB
XML
425 lines
15 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>
|
|
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>
|
|
|
|
<macro name="toc">
|
|
</macro>
|
|
|
|
</section>
|
|
|
|
<section name="Instance Level - read">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://latest.fhir.me/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>
|
|
|
|
</section>
|
|
|
|
<section name="Instance Level - vread">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://latest.fhir.me/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>
|
|
|
|
</section>
|
|
|
|
<section name="Type Level - search">
|
|
|
|
<p>
|
|
The
|
|
<a href="http://latest.fhir.me/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 with a String Parameter">
|
|
|
|
<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 By 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. 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="Chained Parameters">
|
|
|
|
<p>
|
|
Search methods may take multiple parameters, and these parameters
|
|
may be optional. 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="Date Parameters - 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="Date Parameters - 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>
|
|
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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>
|
|
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>
|
|
|
|
</section>
|
|
|
|
</body>
|
|
|
|
</document>
|