I have learned so much from my partner Audrey Watters over the twelve years I have been with her, but one of the most powerful concepts I have picked up from her and ran with in my own way is the importance of storytelling. Not just the importance of it, but really that it is the only thing that matters, and will almost always trump very logical ways of seeing the world that are ubiquitous in the tech sector. A good story will get you further than any perfectly written code or applications, and in a world drowning in technology, stories are not just how you stay afloat, or get ahead, but it is also how you stay sane in all of this. Over the years I have fused my approach to writing code with my approach to storytelling, producing quick and dirty solution solutions for each situation I find myself in.
There are many examples of my approach visible on the web in any given week, but a “production” you will keep seeing throughout this year centers around OpenAPI listing rules in service of what is known as API design governance. One of our competitors in the API space created a very forward thinking approach to listing OpenAPI specifications called Spectral, which allows you to create little JSON or YAML rules that can be applied to “govern” the design of each API using an OpenAPI artifact. Spectral is leading the conversation when it comes to API design governance, but after much studying I found one area that I can both contribute to the open source solution, while also carving out my own slice of the API design governance conversation. Simply by focusing on the storytelling involved with each individual rule, rather than efficiencies involved with actually applying rules.
As with most layers of technology, it can get pretty complicated and overwhelming to make sense of the potentially hundreds of API design governance rules you’ll need to properly lint a robust OpenAPI artifact. In response, the contributors to Spectral have provide a set of “default” rules which you can reference simply by the name, abstracting away the details of each rule, reducing the cognitive load associated with applying 20, 50, or 100+ rules. This is a logical response when you are familiar with Spectral, rules, and the process of listing your OpenAPI. However, I am not just in the business of getting folks linting their OpenAPI, I am also primarily in the business of getting folks to know about API design governance in the first place and the need to lint their OpenAPI. One of the pains I experienced learning about Spectral, and talking with other people who were learning about Spectral, is that we all couldn’t find any rules to learn from. Everyone hides or abstracts away their listing rules in the name of efficiency, productivity, or secrecy, leaving reverse engineers like myself struggling to onboard with what is involved.
As I worked with my team over the last six months to develop a coherent approach to talking about API design governance with Spectral, I noticed that everyone was focused on the technical details of applying rules. Everyone focused on whether it should be done in the IDE, CLI, or as part of CI/CD, and the limitations of rules, and that a rules-based approach will only accommodate about 40-60% of our needs, and that you will need scripts and other more advanced approaches. I found it way to easy to fall down a rabbit hole of technical details involved with apply rules, and to completely forget about the challenges I faced learning about Spectral and API design governance, but more importantly how I am going to get the business and technical masses on boarded with the concept of API governance. You see, very few people give a shit about the technical details of OpenAPI, listing, rules, and the other aspects of what we are doing, and they only care about the pain cause through the lack of governance and the positive outcomes of when you properly apply API design governance. As is my style, I stepped back into my storyteller brain, setting aside my hacker mentality, and began looking for the way to elevate the story over the code.
After stepping back from how to best apply rules, and spending more time thinking about how to help introduce people to rules, I exploded 250+ individual rules into individual hands-on examples of each rule being applied. Going the opposite direction of abstracting away each rule, to shining a light on what each rule did, providing a socially sharable and modular introduction to OpenAPI linting. Having all your rules broken up into 250+ separate little pieces may seem more complicated when you think about applying them, but when it comes to introducing people to what OpenAPI listing is, it gives me 250+ little sharable ways of making an emotional connection with folks via social media, blogs, and other storytelling channels. I am just getting started, but so far the response has been what I desired. I am seeing my rules getting peoples attention and driving engagement, bringing more people into the API design governance conversation. I have gotten a number of people who are already “in the know” tell me there is a much easier way of doing this, to which I kindly reply, letting them know we are playing in two separate games. I get it, my approach isn’t logical from those with the knowledge, my approach is about reaching people who don’t have access to the knowledge. A scene that has played out in my career over and over for the last decade, where people tell me I am wrong for emphasizing storytelling over much more logical zeros and ones.
I am really fascinated with the world of API governance. Not because I think it is something that we should be doing or will benefit the world at large, but because I am fascinated with all the business and politics that exists at this layer. I am intrigued by the storytelling opportunities that exist here. I really don’t give a shit about your API, or even my API, and don’t believe in some utopia where we can deliver the most beautifully consistent API that makes everyone happy. It is a fantasy. What I do care about is the thousands of different ways that we buy into stories at this level, and with APIs powering almost everything around us, it opens up a pretty rich dimension for telling stories, and finding out more about what people believe or don’t believe. It doesn’t matter whether you go with pascal or snake case for your parameters, your API will still suck, but I love the idea of how much PTSD exists out there because everyone is using snake case in your organization while you are foaming at the mouth believing that pascal case is the right way to do things. This is the world of APIs I live for, the dogmatic and entrenched belief structures that leave us believing one story over another, and like Spectral, I can queue up hundreds of little YAML based narratives that further templatize and govern your reality. Using stories to guide, shape, and manipulate a world you think is defined by zeroes and ones, when in reality it is defined and shaped by stories.
