{"API Evangelist"}

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:

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

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:

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

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.