I have a confession, I have written the same application many times, probably just like you. I’m sick of it. I just don’t get the feeling of accomplishment when I implement core API functionality for the 10th time. It just isn’t fun anymore.
The same discussions, the same concerns, and the same technology always results in the same application. I do work as an API designer and developer, so I can see how there is so much overlap between projects. Yet, in retrospect I’m forced to admit I’ve spent a lot of time doing work which wasn’t very novel and could have been better spent adding value to my employers and clients.
The tools and techniques to focus on domain value didn’t exist, and we all work with the tools we are provided, but now there is a way to look past much of the previous work and focus on getting products done.
Hypermedia Web APIs.
Just to be clear, hypermedia APIs are not a silver bullet swiss army knife to do everything you need, but they come pretty close. This post is going to be the start of a series of posts where I discuss hypermedia web APIs and how to leverage their power and minimize the perceived or real pain created by the added complexity.
Guidelines for Designing Hypermedia Web API
The following design constraints will provide a strong foundation for your API design.
- The interface MUST embrace the underlying HTTP protocol.
- The interface MUST document resources and resource capabilities through vocabulary definitions.
- The interface MUST present a home document to publish resources and documentation.
- The interface MUST define all resources atomically, and MUST flatten resource representations.
- The interface MUST NOT couple or document tightly to specific URI paths and patterns.
- The interface MUST NOT include any versioning in its representations.
- The interface MUST expose applicable resource capabilities through hypermedia controls.
- The interface MUST respond to consumer declared goals if the goal is understood.
- The interface MUST be decoupled from hypermedia format, the format MUST be negotiable.
- The interface MUST promote flexible design, it MUST NOT present breaking changes.
- The interface MUST extensively leverage content negotiation.
Got that, no? Well, like everything else these days that is just the tip of the ice berg. The key is to leverage existing standards and functionality to get this done over HTTP.
Over the next few posts I will delve a little deeper into each point, explain why we are bucking some industry trends, and begin a high level review of how to use this guide to design a hypermedia web API.
Much thanks goes out to Mike Amundsen, Steve Klabnik, Ruben Verborgh, and Kin Lane for providing extremely valuable blogs, talks, links, and dissertations to understand this stuff.