Net API Notes for 2021/01/12 - Issue 150

Hello and welcome to the first Net API Notes of the new year! I hope you had an opportunity to rest and rediscover what energizes you during that time.

I originally planned to make a much bigger deal out of the 150th issue. However, recent events at the nation's capitol, along with problems with my newsletter provider, have me under a cloud; more on the latter under the 'Wrapping Up' section.

Let's just get into highlighting a few pieces that deserve to have more attention.
(Meme spotted and shared in the wild by Stoplight's Nauman Ali)



Stripe has long been regarded as one of the premier API experiences. In an epic post, Michelle Bu recaps the first ten years of lessons and guiding principles.

I love detailed breakdowns like this for the kind of regular reminders they produce:

"We frequently felt like we were brute-forcing the problem space, but the enemy of any large design project is not making decisions quickly enough because no option feels perfect."

On any successful API, the development team will change. Do you have this kind of storytelling in place to perpetuate first-principles after you've gone? To explain the considerations that went into why the design evolved to the way it is. There is a camp for which the only documentation is that which is provided by the code. They'll claim, "It's always up to date!". However, this kind of documentation seems just as valuable and, indeed, couldn't be found in only the code.


Hugh Durkin published a piece entitled "Your API is not a Feature. It describes the challenges of introducing API support into a SaaS (Software-as-a-Service) company.

The mistake begins when "API" is added to the feature request list. As Hugh describes, product teams are often rewarded for shipping tangible value. For these same teams, APIs are intangible (darn abstractions!). As such, they risk being deprioritized or, worse, lack feature parity.

Hugh proposes that graduating from "product" to "platform" thinking is key. This switch is making feature parity between experiences, like UI and API, a core tenant.

I believe there's more to why traditional product development struggles when put in charge of creating an API. However, Hugh's post highlights one crucial aspect.


Parler is a Twitter-esque application. The platform is accused of being instrumental to Trump supporters organizing last Wednesday's Capitol attack. By Thursday, infosec circles started circulating an 80 terabyte backup of the site, including posts thought deleted.

While I believe Parler and its users deserve everything they have coming their way, the poor API practices allow us to reflect and apply lessons to our APIs. For example, the key for all posts was an auto-incrementing, numeric id. When a user deleted a post, a "soft delete" was performed. This means a bit was set in the database indicating the post was not to be shown. However, the row itself remained.

That practice by itself wasn't great but often done for expediency. The problem was that the API returned the post, regardless of whether that bit was set. And because the IDs were auto-incrementing, it was trivial to, subsequently, scrape the contents of every post written.

Parler also allowed users to upload and share image and video data. APIs handling this kind of information should scrub EXIF data unless it is essential to the operation of the service. In this case, law enforcement has an archive of geolocation information to work with, which is good. On a dating site where individuals might be in danger of being stalked? No.

Oh, and apparently, the public API used no authentication. So we're clear, that's not good.

There was a hacker news article. It started with "Here is a description of what went down according to someone with far greater technical knowledge than me". It claimed that part of this vast trove of information was due to Twilio service being dropped and two-factor, subsequently, going away. With its claims of "MILLIONS of fake administrative accounts" created, that accounting of events now seems to be bunk.

Parler is now offline and likely will remain that way for some time.



Time for a little back office chat. As of this writing, I have a third fewer newsletter subscribers than I did last month. In short:

  • Google's GMail just happened to go down at approximately the same time I sent out the December edition.
  • All GMail recipients bounced back to TinyLetter, my newsletter facilitator.
  • Tinyletter automatically unsubscribed all bounced GMail addresses from the subscriber list; usually this is desirable for the ones and twos that leave behind their corporate addies when they move to a new job. However, it was catastrophic in this case.
  • Tinyletter claims they have no way to restore the lost subscribers.

The net result is all Gmail users have been unsubscribed. I have no way of reaching them to explain the situation. If you used a Gmail address to sign up for the newsletter in the past and happen to see this online, you'd need to sign up again.

I posted my frustration to Twitter after this happened. It certainly wasn't the way I wanted to start the year.

In happier news, I (finally) got the transcript of my talk, "Why AI Success is API Built" posted online. I hope it will be a useful introduction to AI (and the assorted issues it brings) for folks.

Finally, thanks goes to my Patreons. You're support helps keep the newsletter free for 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.