Net API Notes for 2019/09/26
Next week I'll, most likely, be wading through the artifacts that come out of RESTfest, currently happening in lovely Greenville, SC. Until then, however, I've got an unusually pontificate-heavy edition of the notes.
NOTES
ARCHITECTURAL COMPLEXITY AS ORGANIZATIONAL DYSFUNCTION "SMELL"
In researching and studying APIs, particularly those internal to a company, I see a fair amount of emergent complexity. These are architectural arrangements that may have made sense in the moment they were conceived but, over time, have led the company into a inefficient, or even compromised, position. The reason that this complexity has less to do with technical fumbling and more to do with cultural realities; Conway's law is the example we usually cite as an example.
Nick Tune highlights a different contributor to this complexity in his piece "Organizational Dysfunctions Mirrored as Architectural Complexity".
"Often, significant and unnecessary technical compromises in a software system will be introduced as a result of politics, misaligned incentives, or poor communication."
Nick, then, goes on to provide an all-too-relatable example of the "Accountability Protection Buffer"; Team A, who incentivized to provide an excellent customer facing web experience, is dependent on Teams B through M, who provide APIs. These APIs vary in performance, reliability, and completeness which causes Team A's output to suffer. Team A, having pride in their work and being unable to herd Teams B through M, creates layers of batch fetches, caches, and various other firewalls to minimize the dependencies.
Unsurprisingly, as Nick continues, the immediate solution to Team A's problem actually creates other, more intractable, issues.
"We should stop and frequently ask ourselves: Are we trying to architect around organizational dysfunctions? Are we exacerbating the problem?"
The solution to this kind of problem isn't simple. It also requires someone at a sufficiently high enough position in the org to not only see, but be able to effect change. Answers are hard to come by. But, as they said at the end of the 80's GiJoe cartoons, "Knowing is half the battle".
APIS AND THE BUSINESS RAMIFICATIONS OF BREAKING CHANGES
In this DZone interview of Microsoft Principal API Architect, Gareth Jones, the author, Jesse Casman explores the challenges mentioned in his talk, "Your API Spec Isn't Worth the Paper It's Written On."
Gareth Jones has been delivering a provocatively named talk throughout this year. Entitled "Your API Spec Isn't Worth the Paper It's Written On", folks can watch the Nordic API recording or check out the slides. You can also catch Gareth at either upcoming API World or ASC conferences.
There are a number of intriguing assertions there that any API designer needs to be aware of. One that I'm still dwelling on, and covered in a DZone recap of Gareth's preso by Jesse Casman, is when there is a change that, functionally, breaks an end user experience without any change in the API.
"Huh?"
To explain what I mean, I'll paraphrase the example that Gareth discusses in the DZone piece:
- There is a UI that lists products
- The list is populated by an API and, typically, contains between 10-15 items
- After the UI has launched, a business change occurs (merger, new partner, reclassification of 'parts' to 'products', etc.) happens and the product system of record goes from about a dozen items to thousands
- For the end user, the experience is now broken as the UI struggles to retrieve and render thousands of products.
When we talk about breaking changes, in an API, we're almost exclusively talking about changes made to the API description that necessitate a change by the integrator in order to continue previous function. Phil Sturgeon has a number of non-obvious breaking changes in his piece on API evolution. What is revelatory about Gareth's example, above, is that there wasn't a change to the API description and the experience still broke.
It is a blind spot that, as an API designer, is worth thinking about. In the above scenario, what assumptions were at play? Who's responsibility is it to be aware of future changes? How does that manifest in the code?
AN INTRO TO OAUTH AND THE INHERENT VULNERABILITIES
Roger A. Grimes and Josh Fruhlinger have a primer for CSOs online called "What is OAuth". If you need a high level overview, this might be of use.
One nitpick that I have, however, is that the article uses the same, trite "valet key" analogy to explain the difference between authorization and authentication. Maybe I just hang out in the wrong social strata, but I don't much accumulated experience with either valets or vehicles that have their own valet key. As a result, I find repeating this "example" more confusing than it is clarifying.
What finally clicked for me was a different story. Suppose you're relaxing at home during the weekend when their is a loud knock on the door. Outside there is someone claiming to be the police demanding to search the premises.
One place to start is ensuring the person is who they say they are. This is authentication. To authenticate that they are actually an officer, you might ask to see the person's badge or request the badge number. This authenticates them.
However, just because they are authenticated, they don't automatically get authorization to turn-over your house. There is a second piece of information, a warrant, that would be necessary. The warrant authorizes that action to be performed.
OAuth is for authorization. To authenticate the person knocking on your server's door, you will need to use something else, like OpenID.
Again, maybe the warrant analogy rather than the valet key says more about my background than anything else. But hopefully that helps.
MILESTONES
There was a ton of news this week (at one point I retweeted that 'Today has been a hell of a year'). However, not much of it was API related.
WRAPPING UP
NetAPI.events is my list of in-person API events. There's been a handful tweaks this past week. If you know of a meetup, hackathon, or conference that is missing, let me know. I'd be happy to add it.
Finally, thank you goes out to my Patreons.
Till next time,
Matthew @libel_vox and matthewreinbold.com