HAPI FHIR provides a built-in mechanism for adding FHIR's RESTful Server capabilities to your applications. The HAPI RESTful Server is Servlet based, so it should be easy to deploy to any of the many compliant containers that exist.
Setup is mostly done using simple annotations, which means that it should be possible to create a FHIR compliant server quickly and easily.
The first step in creating a FHIR RESTful Server is to define one or more resource providers. A resource provider is a class which is able to supply exactly one type of resource to be served up.
For example, if you wish to allow your server to serve up Patient, Observation and Location resources, you will need three resource providers.
See Resource Providers for information on how to create these classes.
Once you have created your resource providers and your restful server class, you can bundle these into a WAR file and you are ready to deploy to any JEE container (Tomcat, Websphere, Glassfish, etc).
Assuming that you are using a build tool such as Apache Maven to build your project, you can create your WAR file simply by building the project.
mvn install
Once the build is complete, a file called [projectname].war will be found in the target/ directory. This file can be deployed to the container/application server of your choice. Deploying WAR files to an application server is beyond the scope of this page, but there are many good tutorials on how to do this available on the web.
Many of the HAPI FHIR sample projects take advantage of the Maven Jetty Plugin to provide an easy testing mechanism. This plugin can be used to automatically compile your code and deploy it to a local server (without needing to install anything additional) using a simple command.
To execute the Maven Jetty Plugin:
mvn jetty:run
The server will return data in a number of places that includes the complete "identity" of a resource. Identity in this case refers to the web address that a user can use to access the resource.
For instance, if your server is hosted at http://foo.com/fhir, and your resource provider returns a Patient resource with the ID 123, the server should translate that ID to http://foo.com/fhir/Patient/123. This complete identity URL is used in response headers (e.g. the Location header) as well as in Bundle resource contents (e.g. the Bundle entry "fullUrl" property).
The server will attempt to determine what the base URL should be based on what the request it receives looks like, but if it is not getting the right address you may wish to use a different "address strategy".
The simplest way to do this is to configure the server to use a hardcoded base URL, which means that the server won't try to figure out the "http://foo.com/fhir" part of the URL but will instead just use a fixed value you supply.
The hardcoded address strategy is particularly useful in cases where the server is not aware of the external address used to access it, as is often the case in network architectures where a reverse proxy, API gateway, or other network equipment is present.
This strategy is shown in the following example:
public class MyServlet extends ca.uhn.fhir.rest.server.RestfulServer {
/**
* Constructor
*/
public MyServlet() {
String serverBaseUrl = "http://foo.com/fhir";
setServerAddressStrategy(new HardcodedServerAddressStrategy(serverBaseUrl));
// ...add some resource providers, etc...
List<IResourceProvider> resourceProviders = new ArrayList<IResourceProvider>();
setResourceProviders(resourceProviders);
}
}
See the IServerAddressStrategy JavaDoc (specifically the list of "All Known Implementing Classes") to see other strategies that are available.
The HAPI FHIR RESTful Server will automatically generate a Server CapabilityStatement resource (or a Server Conformance resource for FHIR DSTU2).
This statement is automatically generated based on the various annotated methods which are provided to the server. This behaviour may be modified by creating a new class containing a method annotated with a @Metadata annotation and then passing an instance of that class to the setServerConformanceProvider(Object) method on your RestfulServer instance.
If you have a need to add your own content (special extensions, etc.) to your server's conformance statement, but still want to take advantage of HAPI's automatic CapabilityStatement generation, you may wish to extend the built-in generator class.
The generator class is version-specific, so you will need to extend the class appropriate for the version of FHIR you are implementing:
In your own class extending this class, you can override the getServerConformance() method to obtain the built-in conformance statement and then add your own information to it.
FHIR allows for a number of special behaviours where only certain portions of resources are returned, instead of the entire resource body. These behaviours are automatically supported in HAPI FHIR Plain Server and no additional effort needs to be taken.
The following behaviours are automatically supported by the HAPI server:
| Parameter | Description |
| _summary=true | Resources will be returned with any elements not marked as summary elements omitted. |
| _summary=text |
Only the narrative portion of returned resources will be returned. For a read/vread
operation, the narrative will be served with a content type of text/html.
for other operations, a Bundle will be returned but resources will only include
the text element.
|
| _summary=data | The narrative (text) portion of the resource will be omitted. |
| _summary=count | For a search, only Bundle.count will be returned. |
| _elements=[element names] |
Only the given top level elements of returned resources will be returned, e.g for
a Patient search: _elements=name,contact
|
| _pretty=true | Request that the server pretty-print the response (indent the data over multiple lines for easier human readability). |
The HAPI FHIR server may be configured using the RestfulServer#setElementsSupport to enable extended support for the _elements filter.
In standard mode, elements are supported exactly as described in the Elements Documentation in the FHIR specification.
In extended mode, HAPI FHIR provides the same behaviour as described in the FHIR specification, but also enabled the following additional options:
Values may be prepended using Resource names in order to apply the elements filter to multiple resources. For example, the following parameter could be used to apply elements filtering to both the DiagnosticReport and Observation resource in a search result:
http://base/Patient?_elements=DiagnosticReport.subject,DiagnosticReport.result,Observation.value
Values may be prepended with a wildcard star in order to apply them to all resource types. For example, the following parameter could be used to include the subject field in all resource types:
http://base/Patient?_elements=*.subject
Values may include complex paths. For example, the following parameter could be used to include only the code on a coded element:
http://base/Patient?_elements=Procedure.reasonCode.coding.code
Elements may be excluded using the :exclude modifier on the elements parameter. For example, the following parameter could be used to remove the resource metadata (meta) element from all resources in the response:
http://base/Patient?_elements:exclude=*.meta
Note that this can be used to suppress the SUBSETTED tag which is automatically added to resources when an _elements parameter is applied.