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.
Unless otherwise specified, the examples below show server implementations, but client methods will follow the same patterns.
The read operation retrieves a resource by ID. It is annotated with the @Read annotation, and has a single parameter annotated with the @IdParam annotation.
Example URL to invoke this method:
http://fhir.example.com/Patient/111
The vread 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 @VersionIdParam annotation.
Example URL to invoke this method:
http://fhir.example.com/Patient/111/_history/2
The search operation returns a bundle with zero-to-many resources of a given type, matching a given set of parameters.
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).
Example URL to invoke this method:
http://fhir.example.com/Patient
To allow a search using given search parameters, add one or more parameters to your search method and tag these parameters as either @RequiredParam or @OptionalParam.
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.
Example URL to invoke this method:
http://fhir.example.com/Patient?family=SMITH
Searches method parameters may be of any type that implements the IQueryParameterType interface. For example, the search below can be used to search by identifier (e.g. search for an MRN).
Example URL to invoke this method:
http://fhir.example.com/Patient?identifier=urn:foo|7000135
Search methods may take multiple parameters, and these parameters
may be optional. To add a second required parameter, annotate the
parameter with
@RequiredParam.
To add an optional parameter (which will be passed in as null if no value
is supplied), annotate the method with
@OptionalParam.
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.
Example URLs to invoke this method:
http://fhir.example.com/Patient?family=SMITH
http://fhir.example.com/Patient?family=SMITH&given=JOHN
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 FHIR Specification for more information.
The FHIR specification allows two types of composite parameters:
?language=FR,NL) this is treated as an OR relationship, and
the search should return elements matching either one or the other.
?language=FR&language=NL) this is treated as an AND relationship,
and the search should return only elements matching both.
To accept a composite parameter, use a parameter type which implements the IQueryParameterOr interface. For example, to accept searches for Observations matching any of a collection of names:
Example URL to invoke this method:
http://fhir.example.com/Observation?name=urn:fakenames|123,urn:fakenames|456
To accept a composite parameter, use a parameter type which implements the IQueryParameterAnd interface.
See the section below on date ranges for one example of an AND parameter.
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.
Dates may be optionally prefixed with a qualifier. For example, the
string >=2011-01-02 means any date on or after 2011-01-02.
To accept a qualified date parameter, use the QualifiedDateParam parameter type.
Example URL to invoke this method:
http://fhir.example.com/Observation?birthdate=>=2011-01-02
Invoking a client of thie type involves the following syntax:
A common scenario in searches is to allow searching for resources with values (i.e timestamps) within a range of dates.
FHIR allows for multiple parameters with the same key, and interprets
these as being an "AND" set. So, for example, a range of
DATE >= 2011-01-01 and DATE < 2011-02-01
can be interpreted as any date within January 2011.
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)
Example URL to invoke this method:
http://fhir.example.com/Observation?subject.identifier=7000135&date=>=2011-01-01&date=<2011-02-01
Invoking a client of this type involves the following syntax:
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.
HAPI allows you to add a parameter for accepting includes if you wish to support them for specific search methods.
Example URL to invoke this method:
http://fhir.example.com/DiagnosticReport?subject.identifier=7000135&_include=DiagnosticReport.subject
FHIR supports named queries, which may have specific behaviour defined. The following example shows how to create a Search operation with a name.
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.
Example URL to invoke this method:
http://fhir.example.com/Patient?_query=namedQuery1&someparam=value
The create operation saves a new resource to the server, allowing the server to give that resource an ID and version ID.
Create methods must be annotated with the @Create annotation, and have a single parameter annotated with the @Resource annotation. This parameter contains the resource instance to be created.
The following snippet shows how to define a server create method:
Example URL to invoke this method (this would be invoked using an HTTP POST,
with the resource in the POST body):
http://fhir.example.com/Patient
The following snippet shows how the corresponding client interface would look: