Net API Notes for 2020/04/23 - Issue 128

There are a few things in thought-garden that aren't quite ripe for harvest. While I continue to weed and water those, let's pluck a few choice bits from the internet to share.

NOTES

FIVE COMMON MISCONCEPTIONS ABOUT APIS

Erik Wilde, as a recent addition to the Axway Catalysts, has been producing many articles and talks. One of his recent pieces, for the Nordic API site, is "The Five Common Misconceptions About APIs.

Erik contents that the five most common API misconceptions are that:

• Microservices are Superior to Monoliths, Always!
• APIs Always Scale
• All APIs can be Monetized
• Bimodal IT, Delivered via API, Is a Good Idea
• APIs are Just a Tech Thing

To that list, I'd add a sixth: All APIs Built Should Be REST-ish.

A fair amount of my recent day-job work has been how to reframe developer conversations. Rather than focusing on how to design REST-ish APIs, my team has been defining a repeatable process to define what needs to be built. Prescribing 'all new functionality needs to be an Net API' assumes an architectural pattern before considering the job to be done.

I hope to be able to share more soon.

API STYLES BREAKDOWN

So if REST-ish APIs aren't the only game in town, what else is there? What Net API patterns do developers have to choose from?

Back in ye olden days, when I wasn't bleaching my produce*^, they had these physical gatherings called *conferences. Zdenek Nemec, at the end of 2019, gave a talk entitled "An Expert's Guide to Choosing the Right API Style". The APIs he identified included:

• REST and so-called REST
• Query APIs (mainly consisting of GraphQL)
• Publish-subscribe APIs, like Kafka and WebSub
• RPC APIs, including SOAP and gRPC

Not all of those things are the same. Some are architectural styles, while others are frameworks or protocols that heavily influence the nature of the API. However, all are important to understand when choosing a messaging approach between systems.

The precise definition of the various approaches would be enough to make this a valuable reference. Zdenek goes further, however, and goes into what makes each style right for a particular job.

^ I'm joking. Don't bleach your fruits and vegetables. The application of bleach to fresh produce can be incredibly harmful. Everybody knows bleaching broccoli is how one ends up with cauliflower.

WRITING OPENAPI BY HAND? WHY?

Are you rolling your OpenAPI JSON or YAML by hand? Phil Sturgeon, in a piece entitled "There's No Reason to Write OpenAPI By Hand", laughs in your general direction.

Phil discusses a variety of approaches, including annotations for code-first folks who say "-annotations are closer to the code, which is the single source of truth!" Phil's response, "Don't confuse proximity with accuracy," is brilliant. Just because annotations are near code doesn't mean developers are any more likely to keep them up to date.

There is lots more in the larger piece.

MILESTONES

• The latest version of Spectral, the open-source OpenAPI linting tool, now supports AsyncAPI.
• Have you been reading APISecurity.io? It continues to share the tales of what not to do, like expose 1.4 million doctor records via their API. The prescription to this case? Reasonable rate-limiting, authentication, and filtering by invocation source. More on their site.

WRAPPING UP

Before I conclude this issue, I need to issue a quick correction. In the last edition, I said that Vladik Khononov borrowed a rule-of-thumb from architect Randy Shoup. Vladik was kind enough to reach out and let me know that what he borrowed was the analogy of public interfaces as "front doors", not the heuristic I quoted. Fair enough!

Have you been to NetAPI.events yet? It includes numerous rescheduled conferences and virtual-events. If you have updates on upcoming API-related community gathering, let me know! I'd be glad to share it in an upcoming letter.

The AsyncAPI virtual conference was yesterday. They did several thoughtful things to mitigate a number of the problems that can arise:

• The talks were pre-recorded and played back to the audience, thus avoiding time-sapping and awkward technical snafus and dropouts.
• Because the talks were recorded, speakers could do multiple takes, do light editing, etc. This contributed to polished presentations.
• Presenters were still present during the playback and were able to answer YouTube chat questions, in real-time.
• After the recorded portion, the stream switched to the live presenter for an additional Q&A wrap-up.

All-in-all, kudos to the AsyncAPI team on overcoming adversity and providing a great model of how things can be done. You can replay the event on YouTube. Either start at the beginning or skip around. For example, James Higginbotham's excellent talk, "Event-Based API Patterns and Practices" starts at the 5:07:02 mark.

Finally, thank you to the Patreons who support this work. I continue to be flattered by those that support this work. I'm blessed to be safely sheltered, healthy, and employed. If you have the means, please consider a donation to alleviate the considerable suffering that is happening during this unprecedented time. My family chose to donate our stimulus check to Feeding America, a nationwide, non-profit organization of more than 200 food banks. Another organization worth considering is Youthcare, a non-profit that works with homeless and at-risk youth. There are also a variety of efforts attempting to save small businesses at a time when there is no business, like Binc's Assistance to Booksellers and Comic Retailers.

Have you helped a similar effort? Let me know.

Till next time,

Matthew @libel_vox and matthewreinbold.com