Net API Notes for 2020/08/19 - Issue 139

Typically, I take a break from the notes during August; most readers are MIA with their summer vacations, new articles slows to a trickle, and conference revelations dry up. However, in this pandemic-induced, collective Ground-Hogs day time has lost meaning. Besides, people might welcome whatever distraction they can get.

So, onto the notes!

NOTES

POOR API DEPRECIATION POLICY IS KILLING GOOGLE CLOUD PLATFORM

If you have spent much time in the technology punditry space, you might be familiar with Steve Yegge. The former ex-Amazon and ex-Googler has made a habit of rants as boisterous as they are meandering. There can be some wheat there, however, if one is willing to thresh the chaff. For example, the apocryphal Bezo's Memo story came from his earlier writing (ie, the "build services or you're fired; have a nice day!" story).

In Steve's most recent rant, he articulates something that any API maintainer will be all-too-familiar with: deprecation policy. People build on top of a successful API. That integration is to both the documented behavior and the observed operation (as known as Hyrum's Law). Changing that interface creates work on the part of the integrating developers.

Using cloud services means using APIs. Those APIs should be stable. Unfortunately, according to Steve, he gets this kind of email from Google's Cloud Platform a lot:

"Dear Google Cloud Platform User,

"We are writing to remind you that we are sunsetting [Important Service you are using] as of August 2020, after which you will not be able to perform any updates or upgrades on your instances. We encourage you to upgrade to the latest version, which is in Beta, has no documentation, no migration path, and which we have kindly deprecated in advance for you.

"We are committed to ensuring that all developers of Google Cloud Platform are minimally disrupted by this change.

"Google Cloud Platform"

(To be clear, he's paraphrasing. I hope.)

A bit further down, he contrasts the Android teams' pains to ensure backwards API compatibility, verses the Google Cloud team:

"Backwards compatibility comes with a steep cost, and Android has chosen to bear the burden of that cost, whereas Google insists that you, the paying customer, bear that burden.

"You can see Android's commitment to backwards compatibility in their APIs. It’s a sure sign, when there are four or five different coexisting subsystems for doing literally the same thing, that underlying it all is a commitment to backwards compatibility.

- a bit further on -

"Google's pride in their software engineering hygiene is what gets them into trouble here. They don’t like it when there are lots of different ways to do the same thing, with older, less-desirable ways sitting alongside newer fancier ways. It increases the learning curve for newcomers to the system, it increases the burden of supporting the legacy APIs, it slows down new feature velocity, and the worst sin of all: it’s ugly. "

Change happens: markets, business strategy, team composition, technical aptitude all change. However, the more we can abstract that complexity behind a robust and stable interface, the more time and energy API consumers will have to focus on their unique problems.

That's why API-Design-First is such an incredibly important approach to API development. You won't get the design right the first time. There will be iterations. However, an ounce of prevention is worth a pound of cure. You'll churn less, navigate around traps, and proactively communicate those emerging areas likely to be problems in the future.

And, hopefully, not be the inspiration for the next Yegge rant.

API WORST PRACTICE LEADS TO CONTRACT TRACING APP DEBACLE

Albion College is a small liberal arts school in Michigan. To detect and limit the spread of Covid-19 among its student population this fall, it required all students to install a contract-tracing app. The app, called Aura, tracked student's locations 24-7. As reported by TechCrunch, students either used the app or faced suspension.

Aura was created by a recruiting firm called Nucleus Careers. Interestingly, they appear to have no prior experience building healthcare apps. That would explain why, on launch, the app had two serious security vulnerabilities. The inexperienced development, combined with the rushed timelines, together make an off-putting ditty I call, "API-a-no-no".

First, the secret keys for the app's AWS API connections were hardcoded in the app. The keys were not limited. Instead, they allowed full access to patient data including Covid-19 test results, names, addresses, and birth dates. Aaron Parecki explains the secret-key problem in more detail in an Okta post from last year. For a breakdown of the solution, proof key code exchange (PKCE), try OAuth 2 for Native and Mobile Apps.

The second hair-on-end moment is when TechCrunch realized the app had used an auto-incrementing identifier for each Aura user. This identifier, subsequently, was baked into a URL that was called by the app. Going directly to resource and incrementing or decrementing the number result in a different Aura user's test result being returned. In addition to the test, the page also returned the student's full name.

This offense is so common that I've covered auto-incrementing values before. Just because somebody is authenticated, doesn't mean they are authorized to access a resource. You should avoid making individual user resources guessable. However, if you are going to bake an identifier into the resource, you MUST make sure the requester is authorized to view the information.

I'd love it if APIs, like the ones used here, facilitated a return to some normal approximation. However, eschewing common practice for the sake of speed is only likely to make the problem worse.

MICHAEL SCHARHAG'S INTRODUCTION TO HYPERMEDIA APIS

Let's end the notes with something positive.

Michael Scharhag has, perhaps, written one of the most succinct and understandable guides to hypermedia that I have ever read. This may be old hat for long-time practitioners. However, I'm constantly reminded that our industry continuously replenishes itself; the same people punching the clock, mining those 1s-and-0s today in their respective company towns are are not the same folks as even a few years ago. As our practitioners continue to renew themselves, so too does our storytelling.

Michael clearly outlines why linking is useful, how to accomplish it with straightforward examples, and ends with carefully measured thoughts on where the approach falls short.

Lovely stuff.

WRAPPING UP

Netapi.events is a collection of online API events. Check-out, tune-in, and skill-up your API practice. If you see something missing, let me know, and I would be glad to add it.

Finally, thank you to the Patreons who support this newsletter.

Till next time,

Matthew @libel_vox and matthewreinbold.com