The Soul of a New Machine was a Pulitzer Prize winning book written by Tracy Kidder. It chronicled two computer design groups attempting to create the microcomputer of the 1980s. The "Soul" referred to the essence of the machine they toiled to bring to life. It was the summation of the people who played a part during creation. As stated on the Wikipedia entry:
"The soul is theirs, stored in silicon and microcode."
Lately I've been spending a fair amount of time thinking about not just APIs, but API Products. In doing so, I've become aware that there is another level of mental perception required in order to create them. Anybody can sit down and, in an afternoon, become up to speed and the mechanics of a RESTful API; these are things like what verb to use where, status codes, and resource creation. A person can use their favorite language and quickly put together something that checks all the functional boxes to be called an API. But that doesn't make a good API Product.
An API product should have character. It should have a personality. It should display the best intentions of its creators by optimizing for the consumer. It should have a soul.
What does a technical implementation with "soul" look like? I was reminded of this while watching a (fairly) recent presentation by John Musser. At 10:15 he discusses why REST is preferable to SOAP, and at 16:44 why developers, overwhelmingly, have chosen JSON over XML. In both cases it would easy to mechanically dictate these revelations to teams creating products: "if your API isn't RESTful and passing JSON payloads, you can't deploy". But that doesn't engage the teams into thinking about the character of the API they should create — APIs that, like REST and JSON, are simple to consume, lightweight, readable, and make sense to both humans and machines.
We should know the character, or soul, of the APIs we want to expose publicly: intuitive, flexible, solving a business objective in a meaningful way and — dare I say — delightful to use (where it makes sense). Are there others? Different characteristics warranted by the industry one is in?
With those desired properties defined, we can shape and guide the conversation about everything that comes as part of the design; in the same way that simplicity enticed developers to adopt REST over SOAP, our characteristics should drive our API developer's decisions over ontology placement, payload representations, etc.
It is tempting to try and shortcut API design. A company could attempt to imbue disparate teams with knowledge and experience (sometimes won over the course of years). But, for the sake of expediency and consistency, many API creators are handed a checklist of "company guidelines" and told them to blindly adhere to them. At best, this leads to functionally competent, but wrote, designs. At worst, it creates a culture where developers become divorced from outcomes and asking a centralized governing or deployment body to "just tell me what to do to deploy". In this case, the education gap introduced for sake of speed doesn't just persist; it is exacerbated as the number and complexity of APIs grow, requiring ever more gatekeepers and "expert" oversight to maintain the facade. The "best practices" have gone from being a kickstart to a crutch.
"for a while, we eliminated 'best practices' as a phrase at work because it was becoming a crutch and it was stifling any new or innovative thinking" - @lindybrandon
"I hate 'best practices' as a phrase.. I prefer 'common patterns' because the opposite of best is worst while the opposite of common isn't necessarily bad." - @caseysoftware
There is still a vital role performed by API governance. But those creating the API product need to have the best understanding of the potential consumer's needs and use cases. This understanding needs to be the characteristics upon the which the API is built, even if that supersedes general best common practice.
If the totality of API common practice is a toolbox, then it is not a matter of educating teams to "use a hammer". When building API products, we need to be educating teams when to use a hammer, and when to grab a different tool to express themselves. The soul of the new, new machine requires it.
