REST API Notes for 2018/11/13
Another drizzly fall day in the DC area. While the weather is a poor fit for outdoor activities, it is a match for puttering around online. Let's dive into the latest stories added to the REST API Notes compendium.
NOTES
REST VS GRAPHQL; A COMPREHENSIVE BREAKDOWN
We'll start with not just slides, but also video. Zdenek "Z" Nemec recently presented a critical review of both REST and GraphQL API techniques at the Nordic API conference. The slides are available. More interesting, perhaps, is the YouTube video recording.
As expected, there's no silver bullet. One approach is not obviously superior, or the logical successor, to the other. Each approach has pros and cons that need to be carefully assessed alongside the problem it is meant to solve. Z's guidance is important context to beginning that assessment.
API LANDSCAPING
It is one thing to steward a single API experience. But what happens when you're responsible for dozens, if not hundreds, of APIs? What are the new concerns? How do you manage that new ecosystem? It's an emerging field of practice distinct, yet related, to API design. It also happens to be a topic I've been deeply intimate with for the last several years.
The API Academy's Erik Wilde has slides and video for his Nordic API keynote. If foreshadows some of what the Academy has in their upcoming book, "Continuous API Management", out in December. It is an easy introduction to the challenges that emerge in dynamic systems.
If you find this talk resonates with your role and the challenges you're experiencing in your org, there are a number of next steps. The first is a reference architecture for facilitating the change Erik mentions. Without supporting mechanisms for evolution "baked-in" from the onset, best intentions get set in concrete. Those things that, at first, enabled product delivery will become an impediment to responsive, adaptive development environments. Trying to pull this together in a platform, language, and vendor agnostic manner has been a side-of-desk thing I've tinkered with since discussions at APIStrat.
The next is a "soft skills" toolkit for change agents (horrible terms, btw, but I don't have a better ones atm). The biggest challenges, when operating at this level, are not technical, but cultural. Only covering the technical elements and not addressing the cultural elements is problematic. It is like providing all the creamy peanut butter and rich strawberry jelly without providing the bread, or the means, to deliver it. It is challenging work gleaning proven approaches from business press neologisms. The upshot, however, is that that toolkit appears applicable not only to APIs, but any IT culture change.
I've got the "Continuous API Management" book pre-ordered. I'll reserve additional thoughts until I've had a chance to consume it. Expect a book review shortly thereafter.
USING STRUCTURED DATA FOR SUPERIOR API DISCOVERY
Sometimes insight doesn't come in the form of a conference talk or blog post. In this case, there was a great set of sleuthing that took place on Twitter. Bruno Pedro, among others, worked out that usage of schema.org structured datatypes in API documentation resulted in better Google search presentation.
If you create a public API, this is incredibly important. While the evidence I've seen is mostly anecdotal, prevailing opinion is that APIs are not discovered in marketplaces. When somebody goes looking for an API, they Google the capability. Having an enhanced experience appear directly in the search result is a powerful "leg-up" over other offerings. It is also something I'm not sure is widely known.
I'd love to hear more from individuals that have added schema.org pointers to their API documentation markup. How involved was it? Any surprises?
MILESTONES
- GraphQL now has a foundation. The group represents a partnership between the Linux Foundation, Facebook, and a dozen other companies. The aim is to finalize "a list of founding members, establishing a governance structure, raising funds, and electing committees."
- Postman has released its 'State of the API' Survey. There's a handful of interesting tidbits there, including the fact that "most [API] users have fewer than five years of experience". While there are an increasing number of gray flecks in my beard, it is important to realize that the producers and consumers of API still count their years of experience on a single hand. Plan accordingly.
WRAPPING UP
Webapi.events just got its first listing of 2019! If you aren't familiar, the website is a list of worldwide, in-person events. Is there something that should be there but is missing? Send an email at hello@matthewreinbold.com and I'll be sure to add it on the next update. Also, there should be a visual refresh coming (hopefully) this week. For those of you that had become accustomed to the geocities-centric aesthetics, hold onto your pets.com swag, there's a-change-a-coming!
Finally, thank you to my Patreon sponsors. Together, we ensure that I'm properly caffeinated when spelunking the depth of Twitter. As you can imagine, some days that takes more artificial sweetener than others.
Till next time, Matthew