We’ve written a lot about REST APIs on the Swagger blog, but we are always looking to provide new perspectives from throughout the world of APIs.
Hypermedia-based APIs are advocated by a growing community of enthusiasts. Michael Hibay, API Evangelist, and API Architect is one such man who is actively involved in educating the tech world on the benefits of Hypermedia, its pitfalls and how to effectively adopt the style.
While traditional HTTP REST APIs are great for handling multiple types of calls, the problem of handling versioning and deprecation becomes important constraints that can negatively affect the evolvability of clients and servers. This is where a Hypermedia as the Engine of Application State (HATEOS) architectural style can help.
HATEOS APIs can help effectively decouple servers and clients, allowing you to independently evolve and update them without dependencies with each other. This architectural style allows you to use hypermedia links in the response contents so that clients can dynamically navigate to the appropriate resource by traversing these hypermedia links.
I had the chance to talk to Michael and discuss his opinions on his favorite topic, and also got his thoughts on the latest evolution of the OpenAPI Specification — OAS 3.0.
What got you interested in Hypermedia?
Swagger was actually what first got me excited about Hypermedia. I was tasked with having a an OpenAPI Specification profile for an application, and combining elements of HATEOAS (Hypermedia as the Engine of Application State). I was aware of the HATEOAS concepts, though not all that in depth. The more I started digging into Hypermedia-based code libraries and product support, the more interested I got.
Through the education of that process I learned, "Hey, I can't do this and not only I can't do this but nobody can do this because currently they are not something that can be done together." Once I started doing the research, I really just dug down that rabbit hole, what I found is that the solution was hypermedia.
Something I discovered over time is the angst that can sometimes be seen within the community. There's some baggage that comes along with Hypermedia from the reputation as well, so it's a matter of having to change the perspective of a lot of people, but also take what I know and have learned to really help other people solve the problems that they have.
What would you say are the advantages of organizations adopting Hypermedia?
From an organizational and practical perspective, Hypermedia greatly reduces complexity of consumption of an API. It also minimizes infrastructure costs and if appropriately done and implemented, it really reduces the amount of thought necessary to update and maintain the API.
Once an organization has adopted a Hypermedia based approach to REST API development, the learning curve for building the API is pretty short. This allows developers to be much more productive, making resource allocation a lot easier. Hypermedia primarily has benefits for long term and from an organizational perspective if you have a total cost of ownership, maybe 25% of this cost will be the actual initial development period of the API, and you'll spend 75% of your money on everything else after you launch your product.
Hypermedia properties benefit in making long term API evolve-ability and long term costs much, much less because the fundamental property of Hypermedia is that it's easy to mold and evolve over time. When your clients aren't tightly coupled to your servers in a way that like the OpenAPI Specification proposes, you have much more freedom to focus operationally and change representations as needed over time to allow your organization to make those changes very easily.
Seems like organizations have a lot of benefits associated when going the Hypermedia route. What do you think would be some of the push back or the challenges organizations would face?
The proverbial footnote is always that the tooling required to make Hypermedia development easy hasn’t been developed, and that's true. It's also difficult to understand designing an API with Hypermedia in mind, especially when there’s an aspect of consumption. Consumers are typically used to integrating with a CRUD API. It’s hard to change their "I'm looking for a CRUD API and this doesn't look like a CRUD API, what do I do?" attitude. There's a lot of penetration and adoption challenges in education that stand in the way of it.
But recently, what I've come to realize is the biggest challenge is that a lot of the industry is really focusing on the wrong things. While there are a lot of really good Hypermedia formats and really great resources out there, which can allow you to make Hypermedia easier, there’s really no focus on the client. Hypermedia is about making the client easier. And that's actually what I believe is the biggest barrier at this point —the lack of generic clients that lower the barrier to consume APIs to the point where they're as usable to a non-adept, non-technical consumer. A client that brings together the power of evolvability of Hypermedia with the simplicity of calling CRUD APIs with CURL on a command line. And I think that's really what the primary focus should be on. In fact, that's what my talk was about at this year’s API Strategy & Practice Conference.
That’s well put! You touched on design in your previous response on challenges, and I’d like to know how the industry is approaching Hypermedia design.
When you look at designing Hypermedia APIs versus CRUD APIs, you actually have to talk about the domain first, and only then do you model everything back from the domain itself, including the domain model. You talk about resources and what they can do, and then you work backwards from there.
It's difficult to take people who are knowledgeable with OAS where everything is so statically bound, and then project them into an environment where everything is dynamic. But, the important thing I find is that if you're doing Hypermedia design, you actually establish what I’d like to call a design range. Fundamentally, you write your vocabulary, your domain model, and then you work backwards with a protocol binding to make tooling and testing of the day-to-day stuff from a development technology perspective. You come backwards from the domain, then you bind it to your protocol, whatever that protocol may be, in a transient fashion. And then ensure that your clients don't bind to any of those definitions beyond a certain lifecycle so consumers outside of your organization that you can't control are not bound to something like a URL that will change over time.
There are organizations who have adopted Hypermedia, but this adoption hasn't reached critical mass because the consumer adoption is very difficult. A lot of the companies where you find success will be from a client perspective. They will actually control the clients.
According to you, what do you think would be some good examples of organizations or APIs in general which have adopted the Hypermedia format and have been successful?
Comcast is one of the largest organizations I've seen that really uses Hypermedia the most successfully, and at-scale. I'm certainly always ear-to-the-ground to find more.
Do you think OpenAPI Specification 3.0 can cater to a Hypermedia centric organization? If you had to say, ballpark percentage compliance of OAS to Hypermedia, since we know people love data, what would you say?
The OpenAPI specification is fundamentally a great piece of work and a lot of smart people have done a phenomenal job to iron things out. I believe it’s definitely headed in the right direction, and most certainly can help Hypermedia enthusiasts design a great API.
There are still places that OAS 3.0 doesn’t fully cater to a HATEOS based architecture, which is expected since it wasn’t built to solve those problems. The dynamic nature of Hypermedia doesn't post operational and evolutionary difficulties; OAS is fundamentally a static design framework. When you statically define your interface, and bind it to your actual representations that will be put out into the world in URLs, you've created a contract for the entire universe to subscribe to. If you make any changes to the contract, it would send ripple effects throughout your consumers, all of which go against the fundamental nature of decoupled client servers that HATEOS enables.
But for the most part, I think the latest specifications did a great job of really identifying the loopholes that existed in 2.0. OAS 3.0 removed previous inconsistencies within the format to really allow designers to architect great APIs without having an unduly complex format.
What got you interested in developer advocacy and technology evangelism?
[Laughs] I am a new entrant to overall technology advocacy space. My motivation for getting into this is really helping developers not face the same problems that I have done before. I've done all kinds of API development through a bunch of industries and run the gamut from big companies, to small companies, to tiny startups. I really want to help people to not make the same mistakes that I have and smooth the lines and the jagged edges that were difficult to get around in my career.
Our interview with Michael Hibay is part of an ongoing series of expert interviews on the Swagger blog. Check out another popular interview with Darrel Miller, OpenAPI Initiative.