Designing and consuming web APIs is simple, but hypermedia-rich REST APIs can be daunting. At DevReach, Jimmy Bogard addressed this issue and demystified the complexity of hypermedia.
Most developers have at least consumed an API. The concepts and execution are straightforward to both consume and design web APIs. But when that API requires more than a simple message and moves into hypermedia, the complexity can scare you away.
This talk avoids the in-depth analysis of REST APIs, but instead demystifies the complexity of hypermedia. Many talks dig deep into REST minutia, but that's not very practical for most developers (nor do most take advantage of it anyway).
At his session for DevReach, Jimmy Bogard explained how "plain old JSON objects" are acceptably functional, and we've learned to work with them. But there's no context, strong typing, or other clues to make working with them easier.
What's the solution to make that work easier? Hypermedia, which Bogard defines for the purposes of this presentation as the JSON object plus related information layered on top of it to help the client perform activities. He expresses that, in this working definition, as Hypermedia = JSON + Links + URL + Forms/Queries. All of this can be contained in HTML.
The server side of your REST API, he explained, is comparatively easy. It's the consumer side that can get tricky in dealing with hypermedia.
He clarifies when developers should use hypermedia with their APIs: specifically, not in most normal apps. But it does make sense in different scenarios, including when developers need to accommodate disparate clients—or if your client needs to accommodate disparate servers. And, perhaps, even when you're building mobile apps.
The most common scenario where hypermedia makes sense is this: where the client(s) and/or server(s) are developed and/or deployed independently.
Getting Started with Hypermedia
So now you want to use a hypermedia REST API—where do you start? Bogard describes three options, and recommends against the first: building your own from scratch. Instead, he recommends the second option: choosing a standard and working from that. The third option, choosing a standard and extending it, is really only viable when it's absolutely necessary.
He acknowledges that no one solution or hypermedia type will solve all of your problems, but the standards are great starting points.
Given that introduction, he then dives deep into specific examples, with code, to show you how you might effectively implement hypermedia REST APIs in your projects.
About the Presenter
Thanks to Jimmy Bogard for this insightful presentation. He's chief architect at Headspring, the author of the MVC in Action books, an international speaker and prolific open source developer. You can find him at: https://jimmybogard.com/.