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:

Screen Shot 2018-05-30 at 9.31.10 AM

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:

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?

About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

3 Responses to What’s an API?

  1. Yes, very cool. Thank you!
    Also, don’t standardized APIs also imply that organizations/FHIR servers would implement ‘common’ APIs (e.g., would all have a name search) that would expose ‘similar’ data (e.g., name search would return comparable results).
    Let’s say you write an ‘app’ that checks to see what organization know you. Your app includes a ‘name’ search like in your example. You expect the return value to be yes or no but not maybe. You send your query to 4 organizations. One doesn’t support this API. That’s too bad because now you don’t know how to report that back. One says Yes. The other says No. And, the last one says ‘Maybe’. What do you do about ‘maybe’? It was not planned …
    Am I correct?

    • David Hay says:

      Yes – in the case of the FHIR REST API the content returned is also defined (they are resources – Patient resources in the example given).

      So in the case of your app, you would execute the query against the servers of interest and (assuming that the servers support FHIR) each would return a bundle of Patient resources that matched your query. Even if there were no matching patients, you would still get a bundle back – it would just not contain any Patient resources. Your app would need to examine the Patient resources in the bundle, and decide if there was one that corresponded to you (maybe you would check other details like identifiers, address, date of birth, gender and so forth). You can make the server do much of this work by specifying more complex search parameters – see the search page in the spec for details – and experiment using the reference servers.

      So to summarize, you aren’t getting back a ‘yes’ or a ‘no’ – in this example you’re getting actual Patient resources.

      does that make sense?


  2. John Moehrke says:

    Omar is asking about Patient Identity Proofing. FHIR does not solve the identity proofing step. It has Patient as a resource, and that resource does describe that Patient in detail. This detail can be used during an Identity proofing step to find the ‘best’ match. This is somewhat discussed on the Patient resource in the topic of MPI http://build.fhir.org/patient.html#match. Identity proofing is critical to enabling the Patient to be a direct participant with FHIR API, but would be part of the Security/Privacy steps taken prior to use of the FHIR API. see https://healthcaresecprivacy.blogspot.com/2016/02/patient-as-user-becoming-known-to.html

Leave a Reply

%d bloggers like this: