I recently posted the talk I presented at API World 2017. I estimate that there were maybe sixty or seventy people in the audience and a fair number stuck around afterward to ask questions and share their experiences.
I’ve gone ahead and grouped the most commonly asked questions together here for other’s benefit. Also, if API Governance is your sort of thing, check out the nice write up that Kin Lane, the API Evangelist, did on the process and approach that we’re trying at Capital One:
“While talking with Matt about their approach at Capital One, he asked if it was comparable to what else I’ve seen out there. I had to be honest. I’ve never come across someone who had established API design, deployment, and management practices. Were actively educating and training their staff. Then actually measuring the impact and performance of APIs, and the teams behind them. I know there are companies who are doing this, but since I tend to talk to more companies who are just getting started on their API journey, I’m not seeing anyone organization who is this advanced. Most companies I know do not even have an API design guide, let alone measuring the success of their API governance program. It is something I know a handful of companies would like to strive towards, but at the moment API governance is more talk than it is ever a reality.”
We try - but I know we don’t have all the answers. If you’re working through these issues in your own org, please reach out; I’d love to compare notes. Studies show 70% of IT culture change efforts (DevOps, Cloud, Microservices, etc.) end in failure. That’s a pretty depressing statistic. Let’s work together to make things better.
Now onto the questions.
Why share this? If it is beneficial, isn’t it in your company’s best interest in keeping it all bottled up for yourselves?
No, for the same reason Netflix doesn’t worry that sharing its expertise on microservice design in infrastructure management will lead to a rival streaming service. As Adrian Cockcroft, former grand poobah for Netflix architecture, once said:
“People copy the process they see but that is an artifact of a system that is evolving fast.”
That, subsequently, has been colloquialized as “People try and copy Netflix, but they can only copy what they see, which is copying the results, not the process”.
To explain it with a sports metaphor, the New England Patriots have been one of the most consistently dominant franchises for the past fifteen years. If you gave any other team their playbook, is the same success guaranteed? Given the number of times assistants have left for other teams, the answer is no.
As, I hope, my presentation points out, employees’ sophistication, available infrastructure, company culture, and desired outcomes all play a part in defining the right path forward. What I showed is a guide, not a destination. Attempting to apply, whole cloth, without consideration for any of these factors is likely to result in an ill fit.
The tool that you showed for lifecycle management - is it open source?
No, unfortunately not at the time of this writing. For teams looking to try using OpenAPI documents as artifacts that proceed through a governance process, I would recommend giving Swaggerhub a look. Or possibly Stoplight.io. Neither appears to support configuration of editorial and approval workflows. However, many of the other features (issue tracking, source control, style validation) are present.
I may be missing some alternatives. So many of the search results for “API lifecycle management” are about client credential issuance and request throttling. Or, if the tool does address design time considerations, the goal is for a single user, or team, to generate a mocks.
When ‘reality checking’ our lifecycle approach, I repeatedly referenced commercial web publishing workflows. In that space, an item from any number of creators (usually an article, but sometimes a video essay or listicle) proceeds through a series of checks. Along the way, revisions occur which may send the item back for re-evaluation. That model resonated strongly with our need to involve numerous stakeholder groups (product, security, risk, architecture, etc.) on a design.
Much of your talk, particularly the part about metrics, was about communication to executives. But what if I’m just a developer? What if my software governance is broken/horrible/painful/no-good? How do I change that?
Being on the receiving end of a bad (or badly executed) process can be demoralizing. The first step is to understand why; often the effects may be well known (we have to wait a full two weeks after making a request before we get production credentials on our VPC!) without the reason (round tripping to get finance’s approval for licensing requires sign off from, eventually, an accountable executive at the VP level, or whatever). In my experience, even the most egregious pain points in most companies started with the best of intentions (let’s make sure our costs don’t spiral out of control because of a unchecked, erroneous deployment script).
Next, identify those with the power to change the situation. Referring to techniques in Blue Ocean Strategy, it is not enough to articulate the problem (“It takes two weeks to get into production!”). Those with the power to change may, cognitively, understand why a change would be desirable. But they won’t be motivated to change unless they have felt the pain themselves.
“Feeling the pain” is much easier when explaining questionable technical decisions to technical stakeholders. It is more challenging, though not impossible, if those with the power to change the situation are non-technical. When this challenge was posed to my peers, Tyler Singletary, SVP of Product at Tagboard stated the importance of quantifying what the material effect was, either in cost or lost revenue.
Does the pain inherent in the process:
- Cause a significant time increase (and cost-overrun) of implementation?
- Hinder getting an integration with [target company X that has benefit Y that the company wants]?
- Lose Sales?
- Impede progress on Strategic Goal X?
- Cost more to support?
Quantifying the pain makes it go from a geeky abstraction to a business reality. The similarly named (but totally different) Taylor Singletary, who does Slack Developer Relations, had this insight to share:
“I think if I wanted a technical executive to feel the pain, ask them to document something you know has barby edges. To make the non-technical executive feel some version of that pain, ask them to read that same document out loud.”
(Update: 2020-03-25) Since publishing, I have read a number of additional books unpacking digital transformation and shifting corporate behavior. Two of the best are Agendashift, by Mike Burrows, and Switch, by Chip and Dan Heath.
I am someone now in charge of a governance program. What do I do to get started?
First, congratulations! Second, condolences!
IT governance is a challenging intersection of technical understanding, people management, business strategy, and servant leadership. The first step is to recognize which one of those was the strength that resulted in your appointment to the position. In my experience, many that have been put in charge of their company’s API quality were picked because of their technical acumen; they have accrued a history of APIs that delivered meaningful business value and they’ve now been given authority to “fix” other APIs in the company. Having that, you’ll be in a better position to know what you’ll need to supplement, either with personal study or extra resources.
Next, define the desired outcomes. It is tempting to immediately begin defining rules to counter any tiny annoyance that might be at the top of mind. However, jumping to define rules is rushing to employ tactics when what you need is to define is a strategy. If the business objective is to grow paying clients to your API product by 2x over the next year, does it matter that a contractor insists his compound word enumerated values are represented with underscores, rather than camelcase?
The purpose of a governance program is to deliver business value, whether that is avoiding risk, creating efficiency, and/or maximizing return on investment. Make sure to have the long (and sometimes uncomfortable) conversations about expectations in order to define the desired outcomes. Then, work backwards to select the tactics necessary to support it.
