Jump To...

• Operations
• Exceptions
• Tags

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 following snippet shows how to define a client interface to handle a read method.

The vread 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.

Example URL to invoke this method:
http://fhir.example.com/Patient/111/_history/2

The update 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).

Update methods must be annotated with the @Update annotation, and have a parameter annotated with the @Resource annotation. This parameter contains the resource instance to be created.

In addition, the method must have a parameter annotated with the @IdParam annotation, and optionally may have a parameter annotated with the @VersionIdParam

Update methods must return an object of type MethodOutcome . This object contains the identity of the created resource.

The following snippet shows how to define an update method on a server:

Example URL to invoke this method (this would be invoked using an HTTP PUT, with the resource in the PUT body):
http://fhir.example.com/Patient

The following snippet shows how the corresponding client interface would look:

In the case of a server which is able to do version conflict checking, an extra parameter would be added:

The delete operation retrieves a specific version of a resource with a given ID. It takes a single ID parameter annotated with an @IdParam annotation, which supplies the ID of the resource to delete.

Delete methods are allowed to return the following types:

• void : This method may return void , 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)
• MethodOutcome : This method may return MethodOutcome , which is a wrapper for the FHIR OperationOutcome resource, which may optionally be returned by the server according to the FHIR specification.

Example URL to invoke this method (HTTP DELETE):
http://fhir.example.com/Patient/111

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.

Create methods must return an object of type MethodOutcome . This object contains the identity of the created resource.

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:

The search operation returns a bundle with zero-to-many resources of a given type, matching a given set of parameters.

Reference parameters use the ReferenceParam type. Reference param objects being passed into server methods will have three properties populated:

• The resource type (optional): This is the type of resource being targeted, if the client specifies one in the URL.
• The chain property (optional): This is the name of the property on the target resource to search for
• The value (required): This is the actual value to search for. If a chain property has not been specified, this is the ID of the resource.

Example URLs to invoke this method:
Resource by ID: http://fhir.example.com/Patient?provider=1234
Resource by chained parameter value: http://fhir.example.com/Patient?provider:Organization.name=FooOrg

The validate tests whether a resource passes business validation, and would be acceptable for saving to a server (e.g. by a create or update method).

Validate methods must be annotated with the @Validate annotation, and have a parameter annotated with the @Resource annotation. This parameter contains the resource instance to be created.

Validate methods may optionally also have a parameter oftype IdDt annotated with the @IdParam annotation. This parameter contains the resource ID (see the FHIR specification for details on how this is used)

Validate methods must return normally if the resource validates successfully, or throw an UnprocessableEntityException or InvalidRequestException if the validation fails.

Validate methods must return either:

• void - The method should throw an exception for a validation failure, or return normally.
• An object of type MethodOutcome . The MethodOutcome may optionally be populated with an OperationOutcome resource, which will be returned to the client if it exists.

The following snippet shows how to define a server validate 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/_validate

FHIR defines that a FHIR Server must be able to export a conformance statement, which is an instance of the Conformance resource describing the server itself.

The HAPI FHIR RESTful server will automatically export such a conformance statement. See the RESTful Server documentation for more information.

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 @Metadata annotation.

To create a Client which can retrieve a Server's conformance statement is simple. First, define your Client Interface, using the @Metadata annotation:

Then use the standard RESTful Client mechanism for instantiating a client:

The transaction 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.

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 transaction method.

Example URL to invoke this method:
POST http://fhir.example.com/
(note that the content of this POST will be a bundle)

The history operation retrieves a historical collection of all versions of a single resource (instance history) , all resources of a given type (type history) , or all resources of any type on a server (server history) .

History methods must be annotated with the @History annotation, and will have additional requirements depending on the kind of history method intended:

• For an Instance History method, the method must have a parameter annotated with the @IdParam annotation, indicating the ID of the resource for which to return history.
  • For a server implementation, the method must either be defined in a resource provider or have a type() value in the @History annotation if it is defined in a plain provider .
• For a Type History method, the method must not have any @IdParam parameter.
  • For a server implementation, the method must either be defined in a resource provider or have a type() value in the @History annotation if it is defined in a plain provider .
• For a Server History method, the method must not have any @IdParam parameter, and must not have a type() value specified in the @History annotation.
  • In a server implementation, the method must be defined in a plain provider .

The following snippet shows how to define a history method on a server:

The following snippet shows how to define various history methods in a client.

When implementing a server operation, there are a number of failure conditions specified. For example, an Instance Read request might specify an unknown resource ID, or a Type Create request might contain an invalid resource which can not be created.

In these cases, an appropriate exception should be thrown. The HAPI RESTful API includes a set of exceptions extending BaseServerResponseException which represent specific HTTP failure codes.

See the Exceptions List for a complete list of these exceptions. Note that these exceptions are all unchecked exceptions, so they do not need to ne explicitly declared in the method signature.

Tags have very specific semantics, which may not be obvious simply by using the HAPI API. It is important to review the specification pages here and here before attempting to implement tagging in your own applications.