Ruby Video | Hypermedia - Less Hype, More Media Please

Wynn Netherland

Hypermedia - Less Hype, More Media Please

Wynn Netherland

5 talks

Hypermedia - Less Hype, More Media Please

by Wynn Netherland

In the video titled "Hypermedia - Less Hype, More Media Please," Wynn Netherland, a member of the GitHub API team, addresses the often misunderstood concept of hypermedia within the context of REST APIs. He critiques the frequent misapplication of buzzwords in the tech industry and emphasizes the importance of a solid understanding of hypermedia and its practical implementations.

Key Points Discussed:
- Definition of Hypermedia: Hypermedia is described as a logical extension of hypertext, incorporating various media types and linking them together to create nonlinear information flows.
- HATEOAS (Hypermedia as the Engine of Application State): This concept is explored as integral to REST APIs, allowing clients to navigate APIs dynamically through discovered URLs within resource representations.
- Media Types: The necessity for appropriate media types, such as HAL and Collection+JSON, is highlighted for maintaining rich links and resource interactions. HAL simplifies linking practices, whereas Collection+JSON enhances querying capabilities.
- Examples from GitHub: Wynn provides real-world examples of how GitHub’s APIs employ hypermedia principles, showing audiences the practical implications of these design choices.
- API Documentation and Specifications: The importance of well-structured and accessible API documentation is underlined, noting how poorly presented specs can hinder developer understanding and implementation.
- Utility of Tools: Tools like JQ are mentioned for their ability to parse and manipulate JSON data easily, which aids developers in interacting with APIs efficiently.
- Balancing Hypermedia Usage: Wynn stresses the need for thoughtful integration of hypermedia with awareness of its drawbacks and the necessity for meaningful developer support and guidance.
- Final Recommendations: The talk concludes with advice for API developers to focus on usability, clear documentation, and responsiveness to developer needs, along with practical management of interactions using status codes and conditional requests.

The overarching message of the talk is to demystify hypermedia, presenting it not just as an abstract concept but as a valuable tool in creating intuitive, navigable APIs that meet the demands of modern application development. Wynn encourages developers to explore hypermedia approaches thoughtfully while also being aware of the limitations that might arise.

00:00:18.720 I'm Wynn Netherland, as Martin mentioned. I am known as 'penguin' on the interwebs, which is most places. I blog at wind of him, playing only the hits. As Martin mentioned, I work at GitHub, more specifically on the API team. I help out Rick Olson, Jason Rudolph, and some others you may know, pitching in on the API team. I do a fair amount of API support at GitHub, which was one of the things I was pleasantly surprised to enjoy.

00:00:37.140 I always thought that support was not too fun, having done it in a couple of past lives behind the corporate firewall. But at GitHub, it's actually quite enjoyable. So if you've ever emailed GitHub support with 'API' in the subject, it might be me you're talking to. I have a thing for dotfiles. In the last couple of years, anyone here have their dotfiles on GitHub? A couple of hands. Cool. For those who don’t know, dotfiles are those little dot-prefixed files in your home folder that configure all of your tools, allowing you to customize your toolchain.

00:01:18.670 Adam Yanke and I created dotfiles.github.com prior to me joining GitHub. It's a guide if you're looking for dotfile frameworks—ways to organize your dotfiles. Adam and I use a topical framework instead of putting everything in one flat folder. They’re organized into folders by topic, making it much easier to find specific settings.

00:01:42.070 Another item about me is that I care about having an RSS feed. I am probably one of a half-dozen users left in the world who still use RSS. I've been known to angrily add a feed to a public open-source blog if it doesn't have an RSS feed. If I like the writing and want to subscribe, don't make me check back. It's obvious I have no hobbies, so I tend to write a lot of API wrappers.

00:02:03.180 When there's a new API out, for a while, it seemed like every other Sunday I was watching football and writing API wrappers for various APIs. Writing the Octokit wrapper got me my job at GitHub, which we use extensively across our services. Anyone see boxing last week? One of the first requirements for boxing is to use the Octokit library to interact with the API to authenticate your users.

00:02:26.350 When I joined GitHub, you don’t choose your own role; someone else has to assign it. My assigned role was 'flightless waterfowl,' which I embraced. I think I became the de facto API evangelist because nobody else wanted the job. I like to talk, and I like APIs, so here we are.

00:02:55.010 So our industry loves buzzwords; hopefully, you didn’t hear any of them last night at the drink-up. Who’s creating a responsive website these days? Cool, nice. Is your database schema-less? Do you say 'no SQL' or 'web scale'? If you have an API, it has to be hypermedia-driven. These are nice terms but poor decision criteria. I wouldn’t weigh a technology choice based on any of these terms, yet they seem to get all the headlines.

00:03:36.660 So, what the heck is hypermedia? Is there anyone who doesn't know what hypermedia is? If I asked you to define it, would anyone not know? Cool, then my deck was worth the time. One of the first things that you'd want to do is look it up on Wikipedia. Is anyone running a bot in their offices? I can’t get by without a bot these days; it helps me out with doing menial tasks.

00:04:00.230 To define hypermedia, it can be described as a logical expression of the term hypertext, in which graphics, audio, video, plain text, and hyperlinks intertwine to create a generally nonlinear medium of information. So what's hypertext? Hypertext is displayed on a computer or other electronic device with references, hyperlinks to other texts that the reader can immediately access.

00:04:31.780 A hyperlink in computing is a reference to data that the reader can directly follow or that is followed automatically. A hyperlink can point to a whole document or a specific element. You quickly discover the problem with Wikipedia; we’ve all done this—three hours later and you’ve forgotten what you came for.

00:05:05.130 There are a lot of terms around hypermedia, one of which is hypermedia APIs. Does anyone know how to pronounce HATEOAS? Yes, it rhymes with Cheerios. I mean, poor spelling can be made up with branding, right? That if it rhymes with 'Cheerios’? We can't see that there’s a devil in the cereal box.

00:05:26.380 HATEOAS is essentially the REST of REST. For anyone who's been new to Rails in the last three years, it’s worth going back to check the ancient tomes to see the whole REST kerfuffle. A few years ago when REST became the end-all-be-all with APIs, HTTP nerds pointed out the inaccuracies with implementations—it was a growing field of interest.

00:05:55.960 A client enters the REST API through a single fixed URL—think of it as a front door to the API. All future actions from there are discovered within resource representation. You'll get a resource back, from which you can discover all the future actions. Media types are used for the representation; each resource has a media type that describes its format. Resources have multiple link relations to other resources that the API can navigate to.

00:06:29.160 Here’s a simple example: this is the GitHub Status API that we launched a few months ago, allowing you to check the status of GitHub. Here’s our front door URL, which returns a representation that is simply a JSON hash with three links. Each of these is a link relation to the status URL, which I can follow to grab the actual status data.

00:07:08.700 I’m hoping that GitHub is actually up right now; you can see the timestamp when I prepared my slides. Brief detour: has anyone seen the JQ code example included? A few hands. I want to share some of my tips and tools of the trade.

00:07:39.010 JQ is really neat; it’s a command-line tool that helps you parse JSON data. If you're interested, just check my blog for an article on JQ to colorize the output. Using a pull request URL, I can pass data through JQ, allowing me to manipulate and extract specific elements from the JSON response.

00:08:15.620 Consider the example of the commits listing for a repository. I can pipe that through JQ to examine the GitHub repository's commit history. For every item in this array, I can extract the author’s URL property and get all the unique authors for that page of commits. It’s pretty efficient to handle data like this with JQ.

00:09:06.010 Now, returning to hypermedia types. Media types are critical in hypermedia because they contain inherent linking semantics that induce application flow. For example, HTML is a hypermedia type because of the anchor tag. Unfortunately, XML and JSON are not hypermedia types.

00:09:46.190 HTML isn't great for data containers. We tried to put our data semantics into CSS with microformats, which didn’t work well. Hypermedia types are media types that have been built on top of other media types, which sometimes add the required linking semantics.

00:10:15.450 One popular format is HAL, which provides simple linking and data representation. HAL comes in two flavors, but I’m not a fan of XML. HAL allows us standardized linking practices, making it simpler for developers who integrate hypermedia types into their applications.

00:10:55.880 Another hypermedia type is Collection+JSON, designed for managing and querying documents. This format wraps every object it returns in a collection wrapper, allowing metadata like pagination and other details to accompany the primary items, making it more elegant and informative to users.

00:11:57.000 However, the draft specification is full of standard language, making it complicated. Diminishing returns might happen if you try shoehorning your data into special formats, like an Atom format—something I shudder at. Adam said it best; focus on building things with an API, expose things through an API, and not just spend time educating about hypermedia.

00:12:35.060 The reason I want to talk about Hypermedia today is because the GitHub API is often held as one of the best real-world hypermedia APIs. People look at our URLs and think, 'Well, if GitHub is doing this, it must be the right way.' I just want to convey that we’re experimenting here; there are drawbacks and benefits, and it’s not all perfect.

00:13:19.000 Another quick detour—talking about specs—anybody read specs lightly online? I don’t think many people do, and this is the part that bugs me. Specs today are delivered in chunks, which does not lend themselves to easy understanding or readability. There’s a need for a better format to deliver this information.

00:14:06.800 Specs are a pain to write, and media types really depend on these. Your contract is essentially your spec. An API client developer looks at the spec to determine what goes into something like an HTML blob. If you've ever returned data in HTML or XML, everything comes back as a string, which often creates confusion.

00:14:49.570 Using a format like HTML or XML makes primitive types and arrays difficult to manage. When scaling an API, introducing formats within your server impacts how clients interact with your API and where they need to get information. There are good ideas in the hypermedia world, including URI templates.

00:15:49.280 URI templates look like placeholders for parameters that expand into full URLs when executed. This allows you to streamline how your API can process requests. Effective utilization of URI templates ensures better API design and increases usability within the framework being utilized.

00:16:52.820 For hypermedia to catch on, hypermedia agents must become integral. Many suggest that we need to build hybrid media APIs because that’s how the web functions. However, there is a significant difference in how browsers and scripts interact with APIs, essentially because browsers have built-in features that scripts do not.

00:18:05.960 As API developers, we need to automate the walking of links and follow reasonable workflows. You need higher-level machines or tools for managing these requests intelligently. Collective analysis could indicate if certain requests could be cached based on prior interactions.

00:19:04.560 In Ruby communities, Sawyer is a platform that serves as a hypermedia agent built on top of Faraday, a broader HTTP library. It allows developers to define endpoints and automate resource retrieval, including managing relationships between data effectively.

00:19:54.440 Sawyer essentially segregates raw data and relations, so you interact with various resource levels without losing the context of what that data means in reference to other items. We are implementing this approach in several projects at GitHub.

00:20:58.790 It's important to mention that we decided to maintain the underscore URL and the next API has deprecated the links hash because it leans towards simplification. Without needing to recreate the wheel every time we're building something new, we can simply refer to the data structure already in place.

00:21:43.000 In this regard, I’ve been developing a hypermedia version of Octokit that incorporates the hypermedia features of the GitHub API. This project is multifaceted; I’m balancing development across several projects to enhance functionality without causing excessive strain.

00:22:35.040 I often incorporate the hypermedia graph into my talks, referring to the Gartner hype cycle. This describes the life cycle of how technology reaches peaks of inflated expectations and then stumbles into disillusionment before leveling out into productivity.

00:23:34.490 People may currently feel that hypermedia is either on the rise or decline. The take-home message from DHH resonates: use hypermedia links but avoid being dogmatic about them, as there are drawbacks that can’t be overlooked.

00:24:29.370 For the last minutes of this talk, I want to emphasize some of the API real talk. This applies to those developing APIs; how you present your API is as crucial as the API’s functionality itself. Make sure your APIs are usable, and developers can work around any quirks.

00:25:32.020 Overhyping API capabilities can lead to frustration, especially if users perceive an overwhelming amount of hype without the necessary support. One recommendation is that if developers only expose what is essential for using an API, they should provide adequate rationalization for more complex elements.

00:26:29.300 Avoiding design pitfalls is paramount. If your API provides links that developers don't follow, users may begin forming incorrect assumptions based on a lack of guidance. Relying on documented workflows is the best approach, but active encouragement for following the right practices is also vital.

00:27:46.390 Developers often don't read the documentation, making it important to guide effectively. Latest REST trends show a tendency for developers to follow patterns and check if an API continues functioning as expected.

00:28:55.830 One final note is regarding status codes. Developers need to effectively respond to different server responses, including proper management and parsing of the data structure. Also, managing conditional requests (like ETags) provides developers with data without burdensome payload transfers and ensures efficient caching.

00:29:52.420 In summary, navigating the tension within API design regarding data transfer and interactions demands a concise understanding of hypermedia and linking methodologies. While the incorporation of these elements simplifies some interactions, it is vital to maintain a delicate balance to provide efficiency across all queries.

00:31:12.180 On a closing note, I found an excellent resource during the preparation for this talk: The Noun Project. If you’re looking for unique monochrome icons that you can scale to your needs, check it out. Thank you!

Big Ruby 2013