Net API Notes for 2021/04/28 - Issue 160

Notes, notes, notes! Here we go!

NOTES

YAML IS MORE THAN "JSON WITHOUT BRACKETS"

Those of us that write and read OpenAPI have had our fair share of experiences with YAML. The only thing YAML has going for it is that it is the "least bad" of the alternatives. Or is it?

Jakub Rozek has a wealth of YAML experience. And he is here to tell you that if you've only resigned to YAML to save on a few "{}" characters, you're doing it wrong. Jakub presents a thorough yet easily consumable rundown of YAML's features, lists them side-by-side with JSON examples, and highlights where the two featuresets differ.

As someone who has always seen YAML as a means to an end, I appreciate the thoughtfulness Jakub has put into the article. I also have a greater appreciation for what YAML can do. I highly recommend it.

STATUS CODES AS AN AFFORDANCE

Whether a design is physical or expressed as an API, affordances are important. Affordances are the properties of a design that show users what actions they can take. A well-designed handle on a door, for example, will suggest whether somebody should push or pull to open it.

When used in APIs, affordances are usually describing naming conventions, particularly in the URL. A plural form of a resource name, like "/tickets" or "/transactions," suggests a GET will return a collection of items. Or that I need to POST to that resource to create a new instance, which would subsequently be at "/tickets/{ticketId}" and "/transactions/{transactionId}," respectively.

However, we shouldn't limit affordance design to only resources. As Arnaud Lauret points out in his most recent blog post, HTTP status codes are affordances too. Designed well, API users can leverage experience to make reasonable deductions about what actions are possible. Done poorly or run counter to convention, and API providers introduce comprehension overhead to a system.

WHAT ARE EVENT-DRIVEN APIS?

I've talked about event-driven APIs on a few occasions (newsletters #96, #113, #117, #118, #129, and #149, for example). However, I'm not sure if anyone has nailed the canonical event-driven API overview.

That said, WSO2's Dunith Dhanushka comes close. In "Event-driven APIs-Understanding the Principles", Dunith does deep into not only the why but the how: webhooks, websockets, and server-sent events (SSE).

While I like the thoroughness, I would urge caution on anyone considering SSE. Over the past year, browser vendors have hinted that they are shying away from support. While never quite "production-ready", it is dubious whether they will ever be viable. Still, "two outta three ain't bad" (RIP Jim Steinman).

Need to take it to the next level and generate some AsyncAPI documentation for your event-driven API? Check out this list of eight AsyncAPI generators.

MILESTONES

• John Deere's API allowed anyone with an API cookie to dox any equipment owner. It is yet another example of a BOLA-style attack (Broken Object Level Authorization). Just because someone is authenticated doesn't mean they are authorized to perform an action! For this, as well as a host of other API security bug-a-boos, check out the recently released MindAPI, a mindmap of API security issues.
• Prism, an open-source mock server and validation proxy from Stoplight.io, now supports OpenAPISpec 3.1. Get your JSON Schema on.
• Speaking of Stoplight, they announced early access to Elements, "Open Source API Documentation Building Blocks". It seems like an alternative HTML generator to SwaggerUI?
• Checkly, an API Monitoring and Automation tool, joins the OpenAPI Initiative.
• Rob Zazueta, all around API raconteur, is now consulting. If you're looking for an API marketing or product strategy specialist, give Rob a look.

WRAPPING UP

A FEW THOUGHTS ON BASECAMP, POLITICS, AND LEADERSHIP IN TRYING TIMES

This past Monday, web company Basecamp and CEO Jason Fried faced criticism. Social media ire flowed following a company announcement decreeing 'no more societal and political discussions,' 'no more paternalistic benefits' and 'no more committees'. (A humorously annotated version of the announcement was published as a Gist.)

Speculation abounded as to what drove the changes and why they announced these changes now. I have no context for what was happening internally that drove that decision. Apparently, it wasn't much. Or maybe an owner is retaliating after being reported to HR. Whatever the reason, given Basecamp's outsized emulation in the developer community, I want to comment on the leadership (or lack thereof) demonstrated.

The past year has taxed companies like few others in living memory. It is, perhaps, unsurprising that many leaders failed to rise to the occasion. Mandy Brown writes A Working Letter. In the most recent issue, she wrote:

"-the corporate response to burnout has been earnest but superficial: offering meeting-free Fridays and subsidized yoga, plus an extra week or two off—while the Q3 roadmap and OKRs crank along—is like trying to put out a house fire with a glass of pinot. What people really need is months of rest and control and autonomy over their work."

Restrictions over what can be said and who is allowed to say it is a moonshot away from the rest, control, and autonomy that Mandy describes. Creating psychological safe spaces is difficult in the best of times. After this? My people have a word for that: Ufda.

And what about politics? If this year has demonstrated anything, politics has a profound effect on everyone's lives. Pretending that knowledge workers are somehow immune is a luxury that recent history demonstrates we can no longer afford. As James Governor, co-founder of Redmonk, says:

"if the last few years have shown us anything it's that politics is for everyone, and it touches everything we do. if we care for others, which of course we must, then politics is unavoidable. context is everything, and we create the context."

I am proud of the diverse team I built at my previous employer. However, like all that it is worth doing, it comes at a cost. It requires so much more than pithy statements like "hire for culture add, not culture fit". As a heterosexual cis white man, it means I must do the hard work of discovering my prejudices and preconceptions. It means I must acknowledge the role privilege has played in my life. It means sitting with my discomfort and having hard conversations. It means it is my responsibility, not the job of "a token minority friend", to educate myself. Most of all, it means not prioritizing the comfort of my norms over others, even if I have hierarchal sway over them.

The owners of Basecamp stated that they are not willing to do that work. It is more expedient to leave their employees to fend off political ramifications by themselves, except when said politics align with Basecamp's product differentiation ("topics like antitrust, privacy, employee surveillance"). "Give me your labor but don't bother me with the burden you carry" is executive fiat of the most arrogant kind.

It is a shame. I know many software people who emulate Basecamp practices. However, I hope that doesn't continue in this case. "Leadership is growing an ecosystem of strong collective thinking. Your [leaders'] work serves implementers, not the other way around." While this latest move may be exhibit ownership, it isn't leadership worth emulating.

FINAL NOTES

Woof! That got to be a long one. Quickly, I continue to update NetAPI.events. If you know of an upcoming API event, whether it is online or in physical space, let me know, and I'll be glad to add it.

Finally, a thank you to my Patreons. It is because of their support that the newsletter remains free of advertising and outside a paywall. It is because of these few that we all benefit.

Till next time,

Matthew @libel_vox and matthewreinbold.com