REST API Notes for 2017/10/07
Write a newsletter long enough, and you'll be pitched to check out a product. Usually, this is a pretty harmless affair - done ethically, I get to check out what somebody has been cooking up, maybe even get a good story from events, and the product gets a little press. (For the record, if that is how something is brought to my attention, I'll be sure to call it out in the piece.)
Recently, however, I was approached by a member of a public relations firm to check out a tutorial. My API design sensibilities were immediately rankled by the opening declaration that "most REST APIs are CRUD operations after all". It claimed "to save a lot of effort". The rest of the tutorial went on to show just how easy it was to take one's internal data representation and expose it as a RESTful interface.
No, no, and no.
Creating a RESTful API can be challenging. However, after working with teams on hundreds of APIs, correctly defining their bounded contexts remains the most challenging aspect of any design. Database-as-API is faster, because developers skip emphasizing with the consumer's use case, opting for whatever happens to be in the datastore. But it is a brittle, tight coupling that is inappropriate for all but the simplest of APIs.
James Higginbotham agrees with me. At the 2017 API Strategy and Practice Conference, he presented API Design in the Age of Bots, IoT, and Voice. In it he proclaims that "APIs are stuck in the land of CRUD". Going beyond CRUD means creating long-lived, user-first, capability-driven API designs. These are APIs that match a consumer's expectations and solve their problem in a natural way. It is approaching the design from "outside-in" rather than "inside-out". That is harder to pitch in a five minute demo. But it is the difference between a "good" API experience and one that is merely tolerable.
SELECTED 2017 API STRATEGY AND PRACTICE CONFERENCE RECAP
There's a number of notable talks I should mention while I'm speaking of the recently concluded Portland, Oregon conference. The list below isn't exhaustive. However, here were the notable names that regularly came up in twitter discussions. What follows is presented in no particular order:
API DESIGN
- Irakli Nadareishvili, my fellow Capital One associate, was sharing his microservices insight, "The Fallacy of Assuming that Reuse Equals Efficiency".
- Chris Busse, by all accounts, had a great workshop focused on an API-first redesign of a legacy application. The workshop materials are available. Later in the conference, he also presented on contract-first (or API Design First) development.
- Hong Zhang, a Google Senior Staff Software Engineer, shared information about Google's API Methodology and Style Guide.
- Arnaud Lauret continues his impeccable blend of pop-culture references and API insight in his presentation, "Lord of API Design". In it he covers how designs that rely on developers' best intentions suffer over time, impacting API design consistency.
API DOCUMENTATION AND DEVELOPER EXPERIENCE (DX)
- Taylor Barnett shared some fantastic insight in her deck, "Things I Wish People Told Me About Writing Docs".
- Jenny Wanger was kind enough to post the video of her workshop, entitled "How Mature are You: A Developer Experience Maturity Model".
- Ash Hathaway covers API documentation in her talk "Standards and Definitions of Your APIs and Why Words Matter.
- Kristof Van Tomme, continues the API documentation thread with "When API Docs become DX".
- Bill Doerrfeld nails key points in an engaging talk on API Marketing.
API INFRASTRUCTURE AND TESTING
- James Messinger held, what looks like, a fantastic workshop on API testing. For more info, see the full set of material on the accompanying site.
- Sandeep Dinesh, a Google developer advocate, has a recording of his talk "Istio: Open Source Service Mesh for Microservices". Good stuff if the mentions of service meshes from a few week's ago tickled your fancy.
- Jeremy Whitlock provides a great introduction to JSON Schema. If you read one mohawk-effused slidedeck on JSON Schema this year, this is it.
MILESTONES
SLACK CREATES AN OPENAPI 2.0 DESCRIPTION
Taylor Singletary has a great post on Slack's effort to create an OpenAPI-conforming description of their API functionality. It is a recommended read for anyone who may have created a web-based API in the past and is now hoping to connect that API with a wider ecosystem of tooling.
STANDARD UPDATES
Couple of things bubbled up during the month of October that are worth keeping an eye on. The first is that WebSub/Webhooks is now a W3C pull request. The web linking proposal to the Internet Engineering Task Force (IETF) has had some additional errata added to it.
I'd like to say I'm super "plugged-in". My secret, however, is that I just follow Erik Wilde on Twitter.
WRAPPING UP
Be sure to check out webapi.events for conferences, meetups, and/or hackathons happening near you. If you don't see an event that should be there let me know; either respond to this directly or send me an email at 'hello@matthewreinbold.com'.
I'm also still hiring! Are you interested in leading large change at a company with real impact? Do you have software governance experience (or would like to)? Do you have an appreciation for event driven architectures? If so, I'm hiring for an exciting opportunity on my team. Have questions? Let's talk.
Til next time,
Matthew