healthcare API, REST

I need a REST interface

I was thinking the other day – after going through the mail and other daily meanderings, how awesome it would be if I were to have a REST interface. It would work like this: if I became a resource (for example,, then I could receive all sorts of communications in a fashion that would be extremely streamlined. If someone wanted to send a bill to me, just POST it to If someone wanted to check the status of my calendar, simply query for my busy/free times. Of course, it would be secured with OAuth tokens, so I can grant elevated rights where necessary (I wouldn’t want a buddy posting cable bills to me, or telemarketers scheduling annoying calls into my calendar).

This got me thinking, though, on another problem I think about – healthcare and patient empowerment. There is a lot of talk about the pros and the cons of patient data sharing, but I think, in general, it is a good thing. Personally, I am a strong advocate of the Quantified Self movement, and subscribe to self-measuring whenever I can, and fill up spreadsheets, and graph, and nerd out. I understand the limits and challenges, though (i.e., if I were able to notice I am low on iron, I know enough to talk it over with my healthcare provider, before self-medicating and ODing on iron supplements). But, as I collect this information on myself, it empowers me as I move through the healthcare system; it guarantees that each provider is as knowledgable as the last. I am in control of my health, as best as I possibly can.

However, it would be a humongous job for every health care provider and those associated to healthcare to provide me the information they collect on me. Getting paper copies without some sort of incredible OCR system means a lot of unnecessary work. I can’t imagine having a username and password in every hospital for me to access this information. I don’t think OpenID is a decent enough solution (the permanency of accounts concerns me), and OAuth won’t really be viable either (in a distributed repository sense – who would hold all of my tokens?). I think something like Google Health was a good start, but I think, thinking bigger, a solution is possible.

So – back to my opening question – what if I had a RESTful endpoint? Everyone could post relevant healthcare content to me. POSTing to would be an excellent way to deliver content to me personally. How I manage this mailbox of stuff, is really up to whatever application provider I use. If I wanted to parse the raw data and make all kinds of cool graphs (Brad’s Totally Awesome Hematocrit Counts), so be it. And if I wanted to, in turn, share this lab report with another healthcare provider, I could simply share the REST link for a GET, as long as we have an OAuth handshake in advance. I would be my own advocate in the healthcare system. There are tons of uses for this – POSTing prescriptions, medication information sheets, dietary guidelines, scheduling follow-up tests – an integrated system instead of a disparate one.

This wouldn’t be without problems, of course. Handling spam would be paramount, lest I have a lot of garbage to manage. Managing access would have to be incredibly streamlined (maybe this could work in conjunction with the Big Blue Button initiative). Educating the masses to such a system may very well be the biggest challenge. But, there are so many interesting uses of this data – population health, widespread research – that, with the proper controls in place, could change the way we look at health from a national perspective. With great knowledge, comes great responsibility, for sure.

This is a pipe dream, for sure. Especially for a statistic junkie like me. But boy, it sure would be powerful.

api, REST

REST is not the answer for everything

For those that know me, you know how strongly I believe in the power of the style of Representational State Transfer (REST) as the right way to serve the API. You know that I tend to divvy up each twenty-four hour day between RESTing and resting. You may thus be surprised to learn that I believe that REST is not the solution to everything. Blasphemy, you say? Allow me to explain.

A toasty example

For this example, consider the toaster. It solves an important problem in that it transforms breads into toast. Excellent, I am a fan of toast. We can extend this solution further – for the bagel lover, they have created a button that enables bagel toasting abilities. However, when we consider the domain of warming up other foods, it becomes a bit more of a stretch (shrimp? celery? macaroni and cheese may be a problem, but I believe the outcome would still be delicious – disclaimer, don’t try this at home). One could even argue you could solve world peace by providing bread-toasting abilities all over the world – end world hunger and untoasted bread in one fell swoop. However, there are some things toasters simply can’t solve – like finding words that rhyme with orange. Toasters are complementary to this problem, at best.

Where REST works and does not work

To understand where REST does not work, you must first understand where REST excels. REST revolves around two central pieces – the resource (akin to a real life object), and the simple actions of CRUD (create, read, update and delete). One of the best charts to refer to is the following (from Wikipedia), which maps HTTP verbs to object types:

Collections/bread List of all items Replace the entire collection Create a new entry in the collection Delete the entire collection
RESOURCE/bread/1 Retrieve the one resource Replace the item if it exists, otherwise, create it Not generally used Delete the element

There are plenty of ways to get into trouble with REST, but there are creative and innovative ways to mitigate this. For example, batching can become problematic, depending on back-end behavior. I explored this issue at an API Craft conference – if we transfer an entire diagnostic imaging study from one place to another, and we have a RESTful interface to create a study, series, and individual instances, how do we do this where it is efficient, that doesn’t suffer from race conditions, and that won’t return premature results before the entire study has been transferred? Some RESTful ways to approach this include having special transfer resource end-points, or through the use of locking. It may not be RESTful, but it is RESTy (there’s a difference, see Stephen Colbert’s thoughts on “truthy“). I’ll explore the topic of innovative methods to accomplish complicated goals in a future post.

REST will break down when we are either dealing with unconventional things, or with unconventional verbs.

  • An unconventional thing would be the Image Display actor in the IHE Radiology IID profile. Here, you are not manipulating an object, you are not even retrieving it – you are asking this object to take control of your client to perform some actions. This does not make any sense to do this RESTfully.
  • An unconventional verb would be, for example, “transfer me to over there”. It is not one of the simple RESTful verbs (create, read, update, or delete) – it actually is a compound set of actions. It may also require some work for the client to do to accomplish. Because of this, on it’s own, it cannot be RESTful.

REST will work, beautifully, in many projects, but it is not the solution to end all solutions. Consider it for all your great projects, but do not force it if it does not fit – it will stick out plainly, and your application (and constituents) will pay the price. If it fits, though, it will become a thing of beauty.