REST API Notes for 2018-03-06

Slides and preso and blog post, oh my! Here's your weekly, abridged summary of the best thought in the web API space. Let's break it down so I can get back to my whiteboards. :)

Picture of Filled Whiteboard with Facets of API Design Quality


First up is a massive, albeit wonderful, presentation from Suudhan Rangarajan. Entitled Building an Evolutionary Architecture, it tells the type of story that we don't see enough of: how a system evolves over the course of its maintenance life. It is easy to find glowing accounts of MVPs birthed into existence to fanfare and startup hubris. It is much harder to find accounts of careful reflection, thoughtful pivots, and meaningful compromise. The latter represents a treasure trove of insights that anyone looking to the long-haul could learn from.


API developers can become so inward focused, concerned with the specific implementation made possible by the language or framework that they happen to be using. But, as (I believe) Mike Amundsen once said when describing Roy Fielding's thesis, web APIs are less about the programming the code, and more about programming the web (unfortunately, my searches are failing me at the moment, although I believe it was a post on Mikes blog from ~2011). By embracing simple constraints, the request/response becomes not just about the producer and consumer. Rather, intermediaries along the way can introspect and take action based on the content of the message (this is where that safe/idempotent nature of HTTP verbs comes into play, for example).

Phil Sturgeon's recent presentation on HTTP Caching: Improving Performance and Saving the Ice Caps has been posted to YouTube. I don't think enough developers take advantage of the native toolset they get for free by building on the web. And, if the arguments in the video don't sway you, enjoy the video for the same wit on display as when Phil savagely attacks forum crybabies.


Kin Lane recently posted an interesting argument in favor of runtime-assembled functionality, made possible by an expansion of machine readable APIs. It is thought provoking. A number of people in the IoT and hypermedia camps frequently point to the future of connected devices. They use that as an argument that scaling to that degree will require a different, machine-navigated, approach. But I'm not so sure, at least for a majority of businesses.

We've seen the repeated closing of "open" API programs. Edmunds, retiring it's 'Open' API program in January, is only the latest in a long line of companies that include ESPN and Netflix. Those APIs didn't disappear, however. What changed was that the business decided that controlling the flow of their information had more strategic and monetary value when exclusive to specific partners than it did being open and available to all.

Platforms, with clear monetization models, succeed when their customers succeed; think AWS and its host of APIs for cloud services (see Ashley Hathaway's excellent primer on API Monetization Tips). Company's who create public API programs because they can, whose additional bandwidth and compute costs accrue faster than the revenue/mindshare they gain, who aren't content to be plumbing for someone else's storefront... they are not long for this world. And, increasingly, I see business leadership aware of this trade-off. And they opt for what they know (the partnership bird in the hand) verses what they don't (the promise of birds in the bush).

Creating a photo application that dynamically routes image resizing tedium to the lowest compute-cost cloud sounds really neat. Having algorithms, in real-time, negotiate who has the best price sounds like an awesome engineering challenge and a boon for customer-facing startups. But that world fails to account for the companies providing those services. There are a few specific areas that can sustain a "race to the bottom" pricing strategy. For the rest, there will continue to be people in boardrooms, pounding out deals at the speed of human comprehension. And that will limit the number of companies willing to play in the machine readable, run-time space.

I'm happy, however, to be wrong. What am I missing? Let me know.


It is always fun when APIs "cross-over" to popular culture. This past week, the online comic CommitStrip had a joke about APIs and Hyrum's Law. Hyrum's Law says that:

"With a sufficient number of users of an API, it does not matter what you promise in the contract, all observable behaviors of your system will be depended on by somebody."

That is important to keep in mind the next time somebody proposes exposing "hidden" endpoint for a partner integration in the name of expediency.


As always, has the latest collection of in-person API events around the globe. If you have an event that isn't listed either respond to this note directly or send me an email at ''. I'd be glad to add it.

I also come with not one, but two positions. There is the API technical documentation role I mentioned before. In addition to that, Capital One is also hiring a Master Software Engineer for an exciting, upcoming project. Come work in my neck of the woods - we'll talk shop.

Til next time,


@libel_vox and

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.