API Product Management

What You Missed at RESTfest 2018

Hypermedia Comes Out of Incubation, Balancing Architecture at Scale, & the Relevancy of REST APIs

For those of you who have never been to RESTfest, I’ll begin by saying it’s not your standard conference; an “unconference,” if you will. No one is there to represent their company, yet everyone is on their company’s time to learn, develop skills, hear the latest buzz — and most of all, to network.

We covered a lot at RESTfest Midwest, such as the relevancy of REST APIs, how hypermedia appears to be coming out of incubation, and the fact that someone’s going to win the hypermedia race in the next year or two. Without a doubt, hypermedia was the buzz topic — but it still remains to be seen whether or not the approach can be applied at an enterprise scale, or whether, say, RPC (Remote Procedure Call) is going to make a comeback.


RESTfest 2018: The Highlights

As per the format of the conference, we first all broke up into groups on three topics. One did Open API Specs, another did hypermedia, and in that were two subgroups, in one, Exploring an Existing Hypermedia API, and my side explored How to Document a JSON Hyperschema API.

The group that did the document went in 2 directions. In one, I worked with Adam Magaluk from Apigee on a Javascript program that would take a JSON Hyper-Schema and generate an HTML webpage from it. We were able to generate this easily — the purpose being to present a human-readable documentation from an API. Because a typical schema, which might look like:

… might makes sense to someone like me, but a business person will want a more legible format. So we made:


There was another guy, Ben Greenberg, from the Comcast group who took a different tact. He created something in Graphviz that would print out a graphical chart of all of the links within a file, as well as descriptions and directions on which way those links worked, and what they were. So like for a blog that has an author — you would have “blog” as the object and then an arrow pointing to it that says “author”, and then have the definition down below.

At the end of the day, we demoed what we had built, had some chats and drinks at Grand Rapids Brewing Co., then attended a panel discussion in the current state of REST. Most of that discussion was about hypermedia.


Hypermedia: The Next Level of JSON, Swagger, & OpenAPI

In a Swagger document or a JSON schema document, you have all of your definitions that your service uses. In hypermedia, not only do you define those definitions, but then you define the other definitions that those definitions link to.

For example, If you have a “blog post” definition and you have an “author” definition, a “blog post” has an “author”, but an “author” has one or more “blog posts”. You want to maintain that relationship, but instead of embedding them together, and saying that an “author” is part of a “blog post”, you want to keep them separate and then define in your API how those link and then how to access each one individually. So essentially, you can maintain the relationship, without actually coupling to the other resource.

There are lots of different competing formats, like Siren, Hal, Collection+JSON, and Alps, a new one brought up at the conference. They’re all aiming to define an array of object definitions, how those link together, and how to access each from another. Then Siren and Hydra (and a few others) try to find what actions you can take on each object, as well as the actions you can take when pursuing a link to another action.

How would that be used? Say you’re on a blog post and you can see the author, but you want to know if you can update the author, if you can delete the author, if you can grab more information about the author, etc. You want to know which actions you can perform based on what’s defined or your access control level. So if you’re not an administrator — you can only get the author, but as an administrator, you can also update and delete the author information.


A Brief Background on Hypermedia

Hypermedia has been very theoretical, or a hobby pursuit until recently. Many of the big companies haven’t started touching it at all yet; it’s a niche technology in a big way. Because the service has to have a RESTful use case, and then you have to apply the hypermedia to make it a fully self-discoverable, self-describing application, just using the spec.

One of Vimeo’s guys, Aaron Hedges had a bunch of examples he had implemented on a small part of the Vimeo platform; they’re trying to readjust so their whole API platform like that and that way they could support better embedding across other websites they integrate with CMS’s like Drupal, Dragonfly, etc. So with that capability they can provide an API and then the CMS’s can integrate by building their own smart client on top of it. And then the CMS is saying okay, so you want to embed a video… the CMS knows how to handle the Vimeo API, and so the Vimeo API is self-documenting.

So if it changes, say right now you can “like” something, and the “likes” would feed all the way back to Vimeo so you can see your combined total from, say, all of your CMSs. Later on, say they add a “love” or “laugh” button — When they add other buttons, what they want is for the CMS to see that the new action is available, figure out how to display that action, this way they can call the API to be able to do that.


The Problem With Hypermedia

In the keynote, we ended on the topic that once you have hypermedia as a concept, and then you define a format for the hypermedia like Hydra or Siren, what we don’t have a generic user agent. Currently, with RESTful servers there’s a very common user agent — the browser. But there’s no generic user agent for hypermedia APIs. There’s no way to automatically process links.

What needs to be built is either a browser extension or a completely new platform that does allow hypermedia. So someone can boot up that agent and when a hypermedia API is found, they can automatically use it to browse the data, to go throuh the API and see the actions render automatically, the links render automatically. Nothing like that exists. There are a number of startups or open-source projects working on that right now, and most people at the convention saw that as the next hurdle. Whoever gets there first will be the winner of the race.


Interesting Highlights from the 5×5 Talks

Adam Magaluk from Apigee had a really interesting talk — how to implement hypermedia formats on MQTT. So today most of our stuff is HTTP. There are a lot of headers and overhead that slow it down, but it’s good for public web. However, within Apigee they’re investing in a platform called Zeta, which does IOT concepts, like tracking sensors to gather data about a large area, or harvesting little datapoints to make big assumptions. They’re inventing now on Siren, but in order to solve the problems of IOT (because those little devices can’t handle loads of processing), they’re using MQTT, which is an update from Microsoft MQ; there’s not a lot of overhead there, but hardcoupling occurs.

This meets a great use case for when the devices are connected behind a firewall and occasionally need to connect to the internet, and the data needs to be flowing both ways. His question was, how can we implement this without using HTTP? How can we still get headers and apply a hypermedia approach using such a different protocol set?

That’s all we’ll cover for today. Stay tuned for a post on my 5×5 presentation, Balancing Architecture at Scale, later this week.



Related Articles