The Importance of Impermanence in API Design

This guest post comes from Lorinda Brandon, Director of Solutions Strategy at SmartBear Software. You can follow her on Twitter or find her blogging regularly at SmartBear.

At the API Craft un-conference this week in Detroit, some of the best minds in the API business gathered to talk over the problems that plague us most. It was a unique event in that the agenda was set and run by the attendees in true meet-up fashion. Quakers will recognize the format – for the conference kick-off, the group sits in silence until someone is moved to suggest a session. You suggest it, you run it and anyone who attends your session also participates in it. The sessions are true whiteboard brainstorming activities, with the outcomes posted into Github for future reading.

One of the best sessions was one called “API Smells”, as in “how do you know if yours does?” As we identified warning signals that you may have a bad API on your hands, we made an interesting connection that came up later in other sessions as well. During a discussion about building extensible APIs that are durable and long-lasting, we found ourselves reversing direction and recognizing that maybe we all need to be better about embracing impermanence – like some of the famous Shinto shrines that are torn down and rebuilt every 20 years, we too tear down and rebuild our technologies on a frequent basis. So maybe our design focus should be less on what matters tomorrow and more on what matters today. We named this the “Shinto principle” and it came up time and time again at the conference.

We’ve seen APIs morph endlessly since their inception back in the 1980’s and there’s no reason to expect that shaping and re-shaping will stop. But we expend a lot of effort in discussing how to make them survive the test of time. The discussion at API Craft started out no differently, with questions about whether we should have specific granular APIs (and lots of them) or fewer, more Function-rich APIs that we continually evolve.

At some point, we realized how many of us were in the process of either re-factoring ancient APIs or writing new ones to stand in front of the old ones until it was safe to deprecate them. In fact, this conversation popped up several times during the two days, especially around Versioning and deprecation strategies. All of which speaks to impermanence. How many of us start off a project, even an API project, saying “this is just temporary”? Certainly, we’ve all built bridges and tunnels that we knew we would abandon once we had a chance to build something more elegant. But how many of us approach a project saying – “I’m going to build a tunnel now and later on, I may change the tunnel or I may just blow up the tunnel. But I am never going to build the more permanent solution.”

This does not presume that your API can’t be elegant. Hence, the parallel to those Shinto shrines that are torn down and rebuilt every 20 years. They are planned out, they adhere to the fundamental requirements of a Shinto shrine, and beauty is built into them. But nobody expects them to last forever – people are stewards of the current incarnation, not owners of the shrine. A similar outlook about APIs might change the conversations we keep having. For example:

Setting Standards - There are those that advocate for standards as a means of having known expectations from each other when we use or expose APIs. And there are those who oppose this type of overhead because it inhibits creativity. If we adopt the same attitude as the builders of a temporary Shinto shrine, does it change the emotion? If we identify those elements that should be standard in every incarnation, does that provide more room for creativity within the internal structure?

Inherent Value - It’s funny how many times we sit down to talk about how to convince execs that we need to build an API or try to determine business models to make money from our APIs yet always end up asking the same question – are we doing this backwards? When they build Shinto shrines, it’s not the shrine that’s important – it’s the kami it venerates. If we look at the API as a means to the end (and an evolving transient one at that), does that change the conversation? Do we spend more time talking about its core value to the business rather than the business’ value to it?

Technology Cults - There was a time, oh young ones, when SOAP was the radical edge, brave new technology that made all things easier. I laud the brave defenders of SOAP in this zealous REST era and I wait patiently for the Next New Thing that makes the next generation of zealots scoff at REST. My point being, if we drag this analogy even further down the road, venerate the kami (in this case, the function of the API) not the shrine (the implementation of the API). If you enter into this discussion with a mindset that sees all technology as impermanent, the religious war seems less strident. This shrine is beautiful and the next one will be too…

Governance - Ah, the dirty word… but here’s the reality – even in a mindset that embraces wabi-sabi, there is a need for the incarnation we have today to be reliable and to meet the needs of all the stakeholders. For us to realize the beauty and value of an API, we have to know that there was discipline and order in its creation and that it will be well-tended for the time it exists. Some Shinto shrines are intended to stand for as long as possible, while others are built with a pre-set lifespan of 20 years. But they are all built for beauty and function, and they are all maintained carefully while they stand.

Be sure to read the next Best Practices article: What the Avocado API Can Teach Developers About Scalability and Innovation