Net API Notes for 2021/02/03 - Issue 152

In the before times, this time of year would be when the API industry begins to cast off its post-holiday stupor. I could skip posting in January and be reasonably assured that I didn't miss any significant postings.

However, in this limbic state, any moment is as likely to produce a nugget of wisdom as another. Seasonality is out the window in this, the 330th day of March 2020. So, without further ado, let's check out some of the great content recently released.

NOTES

GOOGLE'S APPROACH TO API STYLE GUIDES AND GOVERNANCE

Google has a lot of APIs. Like many places with many APIs, it is important to create consistency in how they are designed to lower integration overhead. Often design criteria is captured in something called an API Style Guide.

In "API Improvement Proposals: Google's Take On The API Style Guide", Thomas Bush describes Google's governance approach. API Improvement Proposals, or "AIPs", are the individual rules which subsequent work should adhere to. There are some great tidbits, like how an organization the size of Google only has four AIP editors.

There's a fair amount of additional information about running a successful governance program that is missing. For example, how are stakeholders selected? Who gets a seat at the decision table? How are conflicts resolved? What responsibility do teams have to follow the AIPs? What if they don't - what are the consequences, and who has the job of auditing and enforcement? When a new AIP is created, who's job is it to create the necessary behavior change for adoption?

But that is all in-the-weeds shop-talk. For those interesting in the topic or testing the waters with an expanding API portfolio, this is a nice introduction to Google's process.

ERIK WILDE - REST V GRAPHQL

Erik Wilde is the latest to wade into the GraphQL analysis. In his latest presentation, "REST vs. GraphQL: Making The Right Choice", he looks at three different approaches to managing growing API requirements:

• Design a more flexible REST-ish API with filtering and embedding support
• Begin using the backends-for-frontends pattern (also known as Daniel Jacobson's experience layers)
• Create a Query API, like using GraphQL, to support queries to a graph

Perhaps unsurprisingly, there's no silver bullet. As Erik summarizes:

• Breaking changes are terrible; don't make the decision lightly
• GraphQL makes sense in tightly coupled scenarios
• A thoughtfully designed REST interface should be used for a majority of public/partner situations
• Don't start with the technically convenient, but with the consumer needs in mind

A recorded version of this talk is available on YouTube.

AYNCAPI AND OPENAPI - A MODELING APPROACH

Salesforce's Antonio Garrote recently published "AsyncAPI and OpenAPI: an API Modeling Approach". Modeling can be tricky in the best of situations. Modeling across architectural approaches lack useful case studies.

What Antonio presents here is a solid approach to modeling a vocabulary. He then maps that vocabulary to the common concepts, identifies necessary metadata, and uses metadata with Amazon Neptune, a metadata storage repository. If that kitchen sink wasn't enough, he shows how that AsyncAPI modeling can, subsequently, be used to support GraphQL subscriptions.

Perhaps, the contents of the post is more meta that what most API developers think about as part of their job. What I appreciated about it, however, was seeing these description formats in a different light, one that illuminated more similarities than differences.

MILESTONES

• Superface, a company out of Prague promising automatic API integrations, has raised 1.2 million euros.
• The RIAA is seeking access to the Twitter API to make infringement searches easier.
• The Twitter API team released their Academic Research Product Track. The intent is to address the "post-API" concerns some had about social media access after the Cambridge-Analytica scandal. The move provides academics the ability to study topics ranging from disinformation to emergency response effectiveness.
• Instagram announced a new content publishing API.
• Salt Security released their first API Security report entitled, "The State of API Security". According to their press release, 91% of respondents experienced an API security incident. Granted, that might be a bit of selection bias (a security company polling the people that approached them for security advice). However, there are still some interesting conclusions drawn.
• RapidAPI also released a survey. They found AsyncAPI usage tripled year-over-year while GraphQL doubled during the same timeframe.

WRAPPING UP

This past week, I posted the following to Twitter:

My presos begin with almost a full script. The "meat" is prepared in detail beforehand to ensure that things flow logically. Things like the intro, about me, etc. are glossed over. When I present, I always try to record the event to get the "live" feel; inevitably, "doing it live" smooths rough edges or unnatural phrasing. It also provides feedback on the areas that are overwrought or need more explanation. Then there's the final merge, which combines what has come before with what I've learned since. The result is like the talk I recently posted to my website, "Why AI Success is API Built". Thank you to all of you that have checked it out over the past couple of weeks.

Also, thank you to the Patreons who continues to keep this newsletter ad and paywall-free for the benefit of others.

Till next time,

Matthew @libel_vox and matthewreinbold.com