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.



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 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.


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.



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

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.