What’s an API?

I was asked recently by a clinical colleague what an API is, and why it’s important.

Let’s start with the technical answer. ‘API’ stands for ‘Application Programming Interface’ – it’s a way that one application (or a component of an application) exposes its services (which could be just data, or some operation against data) in a way that allows another application (often called the client) to use it. By using an API, it’s possible to develop re-usable libraries – components that can be used by other applications to develop functionality.

As an example, clinFHIR uses a library called visJs to draw the resource graphs in the Scenario Builder. As the developer of clinFHIR, all I have to do is to create the required data structures, and call the documented API and I get the nice resource reference images that the Scenario Builder supports, like this one:

If I had to write all this stuff myself, I doubt clinFHIR would ever have been developed!

So an API is a good thing, but in the example above, the API only works for visjs – nothing else. If I wanted to use a different library, then I would have to re-write the way that I used it – not a simple task.

Enter the world of a standardized API – which is what FHIR specifies. We’ll use the example of the REST API here, though there are others.

In this type of API, the actual interface is defined by some organization (in this case HL7), and different vendors then implement that interface – i.e. provide an actual API that works in the way that the specification describes against their own data (this is commonly called a server).

Now, a client application can use any server that offers that API, meaning that it can choose the one most appropriate to its needs – whether that be the actual data that the server holds, performance, commercial aspects or some other reason.

Let’s take the example of finding a patient by their name.

The FHIR specification defines how to search for things in general, and the types of search for each resource in particular – here’s the ones for a Patient. (Note that a server is not limited to these ones – it can expose others if needed). In the link above we see that there is a search parameter called ‘name’ that finds people by their name (first or last). It’s signature is:

[server url]/Patient?name={name}

so the following urls to find a patient with the name ‘eve’ will all work:

• http://fhirtest.uhn.ca/baseDstu3/Patient?name=eve
• http://test.fhir.org/r3/Patient?name=eve
• http://sqlonfhir-stu3.azurewebsites.net/fhir/Patient?name=eve
• http://vonk.fire.ly/Patient?name=eve
• http://snapp.clinfhir.com:8081/baseDstu3/Patient?name=eve
• http://wildfhir.aegis.net/fhir3-0-1/Patient?name=eve

Note the similarities? These are all publicly accessible servers – just some of the ones currently available.

Indeed, this is what allows clinFHIR to select any compliant FHIR server to display patient data from.

(Note that a server is not required to expose this API – but if it wants to support finding a patient by their name, then this is the way to do it. And it uses the CapabilityStatement resource to tell a prospective client that it does.)

So by exposing a standardized API, a server allows itself to be called by any client that understands that interface (subject to security and privacy constraints of course) – a core part of supporting the FHIR ecosystem.

And you’ve been using another API to access this page –  HTTP (Hypertext Transfer Protocol) that underpins the Internet – so there’s no doubt that standardized API’s are a good thing!

Cool eh?