The FHIR® API

HL7® FHIR® includes specifications for an Application Programming Interface, or API, based on
established web standards and modern information exchange that has been extended to create
a full interoperability solution for health care. The use of common and widespread technologies
lowers the barriers to entry for using the standard by making it easier and faster to implement
while also opening up development to individuals who do not have health care expertise.

What is an API?
An API is an entry point, or “interface,” that allows a computer program or system to access the features
and data of a different program or system. This entry point defines how data must be formatted and the
types of interactions supported, such as how data can be searched. To be successfully exchanged and
ready for an operation, data must be formatted in the same way. For example, a data field to be used in
calculations cannot accept both “1” and “one” as entries, as they cannot be interpreted the same way.
APIs can be simple, with rigid definitions of data structure, or complex, with different data structures for a
wide array of interactions. The FHIR API mainly involves the access and exchange of data.

Many modern applications, both desktop and mobile, use APIs to retrieve, store, and update data.
For example, a smartphone banking app requests a user’s data from a financial institution through
the institution’s API. Each institution’s API defines the standards and protocols that allow an external
application to access the institution’s data. With the proper security procedures and protocols, the app
can successfully request the user’s data. Ultimately, the user of the banking app can view their data, from
accounts at multiple institutions, in one place.

What is REST?
Many applications run on a mobile device or web browser use the information exchange standard REST
(Representational State Transfer) as the basis for their APIs. REST is a method of exchanging information
using the World Wide Web standard transfer protocol HTTP1 , the underlying internet standard that forms
the basis for all website data exchange. “Http” can be seen at the beginning of every webpage’s web
address, such as “http://www.healthit.gov”.

REST means that each request from any client and response from the server contains all the information
necessary to service the request. The exchange of data using REST is termed a “RESTful” exchange. A
RESTful Resource creates a way to access data through a specific endpoint, using specific structures and
formats. More strictly defined structures and formats enable more-precise data exchange. In FHIR, which
uses such strictly defined structures, a system can target and retrieve just a single data element rather
than receive a document containing a patient’s full record.

1. Hypertext Transfer Protocol

@ONC_HealthIT
 The FHIR® API

To initiate data exchange through an API, the requesting client, such as a smartphone app or server, first
sends a request via HTTP for information. If the information is available, the remote server responds with
a status code indicating success and returns the information in a standard web format. For example,
when a user searches for a location in Google Maps, which uses REST, the web browser is the client. A
request in the web browser looks like the following:

https://www.google.com/maps/place/1500+S+Capitol+St+SE,+Washington,+DC+20003

That tells Google a specific location is being searched for in the Maps system. The request is broken down
as follows:
https://www.google.com/maps – the receiving system (Google) and application (maps)
/place/ – the Resource (place) that is the end point being queried

1500+S+Capitol+St+SE,+Washington,+DC+20003 – the address the user is interested in

Google's Maps application accepts this request and sends back the data allowing the browser to display
the map for that area. While that functionality determines what a user experiences, many RESTful
requests are made in the background in response to the initial request, including loading the basic map
interface, displaying the many map elements, and showing notations for other businesses in the area.

The FHIR RESTful API

FHIR uses REST as the basis for data exchange in its API. Health care data types such as medications,
observations, and patients are represented by their own Resources. Resources can be requested via a
RESTful HTTP command like the Google Maps example above, in addition to interactions like searches or
requests that can be used to find and retrieve the precise information needed. Servers, like those behind
an electronic health records system, are programmed with the types of Resources and interactions
they can support. Third-party applications using the FHIR API can be integrated into an EHR and feed
information directly into the provider's workflow.

Each request using the FHIR API supplies the Resource and an indicator, command, or parameter that
specifies the data needed. The simplest FHIR request returns one Resource of information, like a single
Patient. In addition, a request could return a bundle of information, such as that Patient’s associated
CarePlan and Medications, or a bulk data bundle, like all data on all Patients in an EHR. The request is
structured to tell the application what types and how much of the data are needed.

REST does not directly address privacy and security elements such as authentication and authorization,
which are addressed separately in the FHIR standard.

By using the REST architectural style, FHIR takes the best of existing health information technology
and common internet standards to create a modern method of interoperability. This allows health care
systems to implement FHIR without steep learning curves and leading to faster application design.

HL7, FHIR and the [FLAME] mark are the registered

@ONC_HealthIT
trademarks of Health Level Seven International.