The Hypermedia API Debate: Sorry Reasonable Just Does Not Sell

I moderated a panel of hypermedia experts at API Craft in Detroit last week. One theme that dominated not just the panel, but was also pervasive in the conversation over the next two days of the API event, was how can the hypermedia space, improve its overall image, message, and potentially reach a wider audience, and maybe even converting some of the hypermedia skeptics, to hypermedia evangelists.

After a session at #APICraft, dedicated to understanding all the hypermedia hate, Mike Amundsen (@mamund) and I continued the conversation, where he stated: When it comes to hypermedia, and technology online, reasonable just doesn't sell.

This statement sums up my views of the current state of the hypermedia conversation. I went into the event expecting a very heated debate, filled with very intelligent, passionate, yet opinionated and hard-headed individuals. If you even lightly pay attention to the world of APIs, you probably have stumbled across the conversation between passionate REST practitioners (aka Restafarians), and the more recently the select group of hypermedia specialists—producing an image that is perceived by some as passionate, opinionated, and pushy, or even portrayed as being down right mean, nasty, delusional and confrontational by some.

What I saw on the hypermedia panel last Monday, and over the next two days at #APICraft, was anything but the popular image of REST and the hypermedia community. I don’t dismiss that some REST, and hypermedia practitioners can be rude, mean, and less than tolerant of those of us who don’t quite understand every detail, but this group of hypermedia leaders were anything but. They were humble, articulate, and eager to better understand the hypermedia approaches of their colleagues, and try to understand how to better get the message out to the larger public.

So where does this image come from? I think there are two camps, who are equally to blame: 1) The hypermedia pioneers 2) The hypermedia skeptics — the rest of us are just along for a ride on this hypermedia roller coaster.

First let’s look at from the hypermedia skeptic side:

  • One Client To Rule Them All - You often hear claims, whether true or not, that hypermedia pioneers claim if all APIs were hypermedia, we could have a single, intelligent client to rule them all, and do away with all of the crap we have now—think web browser.
  • Adds Unnecessary Complexity - Adding extra links, and payload to each response just adds more complexity, without any benefits to warrant the added work.
  • Too Lofty, Dreamy, and Still Academic - Many say that Hypermedia is just to big of a vision, and the hypermedia pioneers are too dreamy, and stuck in just an academic discussion—it won’t work in the real world.
  • Solution For All APIs - There are many claims that hypermedia is something that all API designers should follow, applying to APIs in all industries as a silver bullet style solution.
  • Will Prevent APIs From Breaking - When you use hypermedia, your APIs are completely protected from breakage, and your developers will never feel any pain from API versioning, and the evolution of your API.
  • Solves Discoverability - With each payload, you get instructions for what is next, so if you know an API endpoint, you should be able to find everything else from there.

Next let’s look at from the hypermedia pioneers side:

  • Haters Gonna Hate - It has nothing to do with Hypermedia being good or bad, haters gonna hate. There is nothing you can do.
  • They Don’t Care - Nobody even cares about learning new things like hypermedia, so there is no reason to even explain it to them.
  • They Don’t Need To Understand - Not everyone even needs to understand what hypermedia APIs are, they will just benefit from the results.
  • They Just Don’t Understand - Skeptics just haven’t taken the time to understand what APIs are, and would rather just remain ignorant.
  • Its OK to Not Be Perfect - Hypermedia makes it ok to not build your API 100% correctly the first time, allowing you to change it along the way.
  • Use Media Types - People don't read docs, we need to rely on media types help provide the information developers will need.
  • Give Us A Break - This shit is hard, and the hypermedia community is working hard, and taking risks to push APIs forward.

Beyond both the hypermedia pioneers, and the hypermedia skeptic camps, I think the main problem with the hypermedia conversation is as Mike said, "reasonable just doesn't sell”. I think this is the number one illness in the whole debate, that some bloggers feel the need to polarize any debate, sensationalize and use hyperbole at every turn. You can see this playing out in coverage of hypermedia, but also around other areas of the API space like API deprecation, where the argument was either APIs can go away at any moment, to the other end where you have to support APIs forever—not discussing the middle reality which would show there are plenty of APIs who handle deprecation very well, but year, that is boring, and really doesn't sell.

Let’s talk about what the hypermedia pioneers can do to shift the conversation:

  • Strong Implementations - The space needs for examples of hypermedia APIs in the wild, providing as much detail about the implementation, and hopefully a public API that they can actually go play with.
  • Storytelling - There needs to be much more storytelling about hypermedia. Not the technical narrative of your implementation, but a story of hypermedia APIs, and the solutions it delivers. Keep stories, short, inviting, compelling, and published often—we are all busy and don't always have the time to commit to reading longer pieces.
  • Patience - Have patience with the community, this is complex stuff, and it will take time for hypermedia to roll out, get the implementations we need to showcase the potential, the tooling and resources needed to support developers.
  • Friendly - Make sure and keep things friendly—this will go a long way in defusing the skeptics, and you never know you might convert them, one by one along the way.
  • Speak To Management - When you are telling stories, building case studies, and presenting on your work, make sure you speak to management level as well as to developers. It can be the leadership that carves out time for developers to learn about hypermedia, or possibly mandate that it should be part of an API design.

Let’s talk about what the hypermedia skeptics can do to shift the conversation:

  • Make The Time To Read - There is some great material out there about hypermedia, to get you up to speed if you can carve out the time. Sure, we need more examples of hypermedia in the wild, case studies, and tooling, but in the mean time, make sure and read as much as you can before casting judgement.
  • Make Sure And Listen - I heard some really compelling stories around how hypermedia works, and I bet if you take the time to listen to more of the conversation you might at least evolve your opinion of hypermedia.
  • Think Long Term - Hypermedia provides some long term benefits that are often overlooked in the short term concerns about time and resources needed to get up to speed with hypermedia, and actually implement as part of your API design.
  • Don’t Worry About What You Don’t Know - I feel like some of the trolling of hypermedia might be based upon insecurity about what one doesn’t understand. I have to admit I don’t fully grasp everything about hypermedia, but I see enough to grasp the long term potential, and know I should worker harder to close the gaps in my understanding.
  • Don’t Be Mean - I’ve seen some pretty harsh responses to what hypermedia pioneers are working on, and I think it would be easier to just walk away, rather than shitting on someones hard work. Hypermedia pioneers are putting a lot of time and energy into moving the space forward in positive ways.

Ultimately the ball is in the court of the hypermedia pioneers.There really is no reason that skeptics, or anyone else should care, until there is more examples, tooling, and stories around why hypermedia is worth the extra work in getting up to speed, and implementing as part of our APIs designs.

I see hypermedia at the same place, as REST was in 2010 when I started API Evangelist. I had witnessed first hand the solutions a RESTful API provided, and saw what was playing out in the public API space with Amazon, Twitter, and Twilio. As I continue to study the space I saw the RESTafarians arguing, shaming and generally making people feel stupid for not understanding HTTP, and fighting over exactly what REST was. It appeared to me that REST would suffer from the same image problems as the semantic web, and linked data.

The API space needed a friendlier layer, one that would help soften up some of the technical debates, and tell stories that would make all of this valuable knowledge more accessible—with this in mind, API Evangelist was born. I’m not saying I’m responsible for web APIs moving into the mainstream consciousness, it has taken all the valuable implementations available out there to do that, but I do know I’ve started some important conversations by working so hard to help everyone better understand the space.

After what I saw in Detroit last week, during the hypermedia panel I moderated, and over the following two days, I’m confident that with a little more storytelling we can shift the tone of this conversation in just a year or two. It won’t happen overnight, but I saw some really smart, hardworking folks who were very humble about their hypermedia work, and willing to admit there is a lot of work to be done, and eager to help the public to better understand the benefits hypermedia will bring to not just individual API operations, but the overall API space.

If I didn’t believe that hypermedia offered significant benefits, I wouldn’t be talking about it. In 2014 I’m seeing the hypermedia conversation move beyond just the API-Craft forum, beyond just academic discussion, and we are seeing some meaningful implementations of hypermedia in the wild. I will keep working to evolve my understanding and storytelling around hypermedia, while also working with the experts to generate more stories, and examples of their own work.

Update: I changed the word hater to skeptic (except in the haters gonna hate bullet), John Sheehan said I should use, which seems sensible, and following my own advice. Thanks John.