Net API Notes for 2021/05/26 - Issue 163

Net API Notes is a regular, hand-curated digest of impactful news and analysis for busy API practitioners. Are you reading this on the web and not subscribed yet? Sign up today and be the first to get ad-free, actionable info delivered weekly to your inbox.

Welcome to another edition of Net API Notes! This week I'm coming to you from a rain-soaked South Dakota. What's good for the crops is a problem for the satellite internet, however. Let's get to the notes before another storm front rolls in.



Conway's Law has been a regular topic of discussion within the API space for some time. (I've even referenced it on more than one occasion.) However, despite its ubiquity, there's still a lot of jurisprudence when it comes to Conway's Law.

Thankfully, Thierry De Pauw has done a wonderful job capturing some of the best thinking on the subject in his piece "Shades of Conway's Law". He starts with the various initial articulations and then expands to the multiple wrinkles and expansions added over the years. Along the way, Thierry also points out areas that remain vague or require subsequent conversation.

Organizational design is architectural design. Because of this, I've encouraged going beyond rules and checklists in my own API governance work. Someone concerned about the health of an entire API ecosystem needs to be as adept at evolving team boundaries as they are at advising on schema definitions. And articles like Thierry go a long way to explaining why.


Speaking of advising on schemas, Chris Wood and Erik Wilde recently had a conversation (and subsequent dZone article) on applying rulesets with Spectral. Spectral, as you might know, is the open-source JSON/YAML linter. It allows folks to create style guides for their structured data (OpenAPI/AsyncAPI/RAML, etc.).

The article (and accompanying video) walkthrough seven ways they apply Spectral to the OpenAPI pet store example. If you aren't currently using Spectral as part of an automated developmental pipeline, check it out - you might be surprised at how powerful JSON/YAML linting can be to nudging API definitions toward better consistency.


Madan Thangavelu, Abhishek Parwal, and Rohit Patali recently had a comprehensive piece on the Uber Engineering blog entitled "The Architecture of Uber’s API gateway". It is a detailed look into the complexities of providing API access at scale.

Buried toward the bottom of the piece is the curious mention of payload introspection. In my experience, this has been a controversial topic. On the one hand, if the gateway deserializes payloads passing through it, it can perform additional validation. However, that extra action comes with a speed penalty. It also risks re-introducing an enterprise-service-bus antipattern; that is, having intermediaries take on too much of the processing.

In Uber's use case, they've opted to deserialize. That, along with many other documented considerations, make this an article worth considering.



Have you submitted a talk for the 2021 ASC event? The call for proposals closes on June 11th. If you've got a specification story, consider sharing your insight! That conference, along with numerous other API events, can be found at If you know of an upcoming API shindig, whether online or in person, let me know, and I'd be glad to add it to the list.

Finally, thanks as always to my Patreons. These upstanding folks keep the newsletter free of advertising, information selling, or paywalls. Because of their generosity, the rest of the community can keep getting these notes for free.

Till next time, Matthew

@libel_vox and

While I work at Postman, where every Slack notification smells vaguely of lilacs, the opinions presented above are mine.

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.