Hypermedia API
April 30, 2015

The Movement Towards Hypermedia APIs - Is it Happening?


Confession, I was not a believer in Hypermedia APIs. When I would attend a conference and hear the dream behind the academic theory of API flexibility, unbreakable and adaptable clients, no need for documentation among other dreams, I would laugh silently, mock, and say to myself, "Yeah right, these guys do not live in the real world and have never had real enterprise applications and APIs in production." However, the last few months of studying hypermedia APIs and seeing more and more enterprise customers starting to try to use Hypermedia APIs, I have become a convert. Let me caveat that, I am not a convert of the academic theory and lofty dreams, but more of a realistic applied practice believer.

I recently gave a webinar on hypermedia APIs and in that webinar I wanted to understand the level of knowledge, maturity level, and usage of hypermedia APIs within the audience. I wanted to gauge the number of believers and hopefully at the end plant the seed of hope in the non-believers. Throughout the webinar I polled the audience. I think it is important to share the results so that you know where you stand in comparison with the industry.

Richardson Maturity - Most At Level 2. Are You?

I asked the audience to assess the level RESTFul maturity in their organization based on the Richardson Maturity Model. This model has four levels.

Richardson Model
  • Level 0:  The Swamp of POX - At this level you are dealing with mostly plain old XML, a single endpoint and using just the POST method, most likely with SOAP
  • Level 1: Resources - At this level you have defined resources such as book/1 and book/2 but still using a single method, again most likely POST
  • Level 2: HTTP Verbs - At this level you use the HTTP verbs GET,PUT, POST,DELETE properly and use the appropriate response codes.
  • Level 3: Hypermedia Controls: At this level you are utilizing HATEOAS (Hypermedia as the Engine of Application State).  You have reached Roy Fielding definition of RESTFul APIs and the "Glory of REST".
Richardson Audience Maturity
Based on the Richardson Model, which maturity level are most of your APIs at today?

The results were as I would have suspected. 44% of those that were surveyed were at level 2 on the Richardson Maturity Model. Most enterprises I have visited over the last two years have taken a giant leap towards REST APIs. The enterprise APIs for both internal and external use that we are now seeing are being designed far better then they were only a year or two ago, therefore there are fewer companies getting stuck on Level 1. That being said, there is still a lot of SOAP in the industry that I do not see going away, especially for internal enterprise use. It was great to see that 7% have attained Level 3 and the Glory or Rest, but maybe that is another survey questions I should have asked. Are they seeing the glory?

How Well Do We Know Hypermedia APIs?

The disadvantage of a webinar over presenting at a conference, is that there really isn't a mechanism to gauge who your audience is and their level of maturity about the subject that you are presenting on. You have no ability to get any verbal or physical signs that you need to change course in a presentation to match the audience maturity or interest levels of ones audience. That is why the next polling question was extremely important and interestingly, wrt to the Richardson Maturity Model results. The next question was "How well do you know hypermedia APIs?". I gave four possible answers that you can see in the chart below.

Hypermedia Expert
How well do you know hypermedia APIs?

Turns out there was no one claiming to be an expert on the call, maybe they were being modest.  We had a few that were well versed but the majority of the folks that responded were just starting to investigate or were some what familiar. Considering the number of people who responded that they were at the Richardson Maturity Model Level 2 and the nature of the webinar, this was the result I was also expecting. If everyone would have been an expert, they would have been on the wrong webinar.

Yes We Are Using Hypermedia APIs

Almost a third of the people who responded to the question "Are you using hypermedia APIs today?" said yes. Some of you are probably thinking, wait didn't you ask this question up at the maturity level?   No, the maturity level question had the qualifier "most of your APIs". There are several companies who are getting their feet wet with just a couple of hypermedia APIs. In most cases, it isn't just for fun, there is a real reason why leveraging a hypermedia API makes sense. For example in mobile scenarios where you own the client and want to reduce the number of times you need to upload a new version to the app store.  

Using Hypermedia
Are you using hypermedia APIs today?

The Future Looks Like Hypermedia

Wow oh wow!  Almost 2/3 of those that responded said that they are planning on using hypermedia APIs in the near future! 

Planning on Hypermedia
Are you planning on using hypermedia APIs in the near future?

Hal Has the Lead But Others Emerging

Hal is one of the oldest Hypermedia media types in the market besides OData. It has a large active community built around it and is one of the easiest hypermedia media types to learn and implement. It is a very basic and simplistic hypermedia media type but that makes it attractive to start learning with. I am not advocating it, just stating on why it has the lead on this call. OData is also very popular in the enterprise arena and has a large community but not so popular in the developer and API economy arena, which is why I think the results are lower on this survey. OData APIs are "interesting" and I'll leave it at that. JsonAPI is popular as it is similar to Hal in that it is simple and it is geared toward mobile development. Then there are the more forward thinking hypermedia media types such as JSON-LD and UBER which are very new to the market and glad to see there were some representation of those in the survey. I did notice that I left off Mason in the survey questions by accident. Mason is a very new hypermedia media type that came out about the same time as UBER.

Most Used Hypermedia
Are you planning on using hypermedia APIs in the near future?

While this survey shows Hal taking the lead, there is still a lot of churn in the hypermedia world as the industry tries to figure out the best way to represent hypermedia APIs. In the webinar I talk through each of these hypermedia types and the options you have for defining your hypermedia strategy.


Is the movement toward hypermedia APIs happening? I would say yes. Based of the customer engagements I have had in the last few months and as shown in this survey a lot of companies plan to leverage hypermedia. We have a large portion of companies sitting at the Richardson Maturity Level of 2 that are now looking to differentiate themselves and leap frog competition. There isn't a clear leader for which hypermedia media type to adopt. You will have to have to look at each hypermedia media type and make a judgement call. In my webinar I try help you by laying out some options and some details about each media type. You can watch the replay  and get the slides of  "Making Sense of Hypermedia APIs - Hype or Reality".

Try Akana

Click below to sign up for a free 30-day trial of the Akana API management platform.

Try Free