Net API Notes for 2020/10/02 - Governance - Issue 143

Welcome to October!

How are you doing? Are you coping? Are you finding a way through? The weather in the greater DC metro area has been fantastic for answering calls while walking. Pounding the pavement has helped keep me grounded and the bigger picture in perspective.

Speaking of perspective, it has been a few weeks since the API Specifications Conference (ASC) 2020. There were plenty of discussions on various formats. Many were great. However, how does one get an org to use one? I want to spend this newsletter noodling on where I have seen organizations paint themselves into a corner. I also want to propose an alternative way forward that has been the recent focus of my study.

THE ASC 2020 EVENT

First, I should say the organizers of ASC 2020 event did a great job. The OpenAPI Initiative has posted the recordings to their YouTube channel. There was the usual virtual conference growing pains:

• Having to grok yet another software implementation's controls
• Slides with text sizes that may be ok full screen but are too small in the given frame
• Speaking to a screen with notes rather than the camera

Those are minor quibbles, however. Overall, it was a great event that had some fantastic content.

OBTAINING SPECIFICATION ADOPTION THROUGH ENFORCEMENT

Like that of the "What's the Specification for API Products" keynote panel, a fair amount of the event discussed how to get teams to adopt OpenAPI definitions of their intent. That naturally segued to how to maintain common behaviors, practices, or patterns. Collectively, these common design approaches are referred to as API style guides.

"How do I make them do the thing?" is the most common question in traditional command-and-control, hierarchal-style management. In these organizations, OpenAPI adoption becomes synonymous with enforcement. An individual (or individuals) are drafted to serve as the "style police". Interventions made after-the-fact are brutal, so a checkpoint (or checkpoints) is/are established in the path to production. At these gates, the design intent, captured in the OpenAPI description, is reviewed before the development team is allowed to proceed. In the best scenarios, this kind of bureaucracy is tolerated. Poorly done, and it is easy to do it badly, this interruption causes additional communication overhead delay.

Reaching for the automation hammer, in regards to developer things, has always been fashionable. Proponents maintain adding API style enforcement to the CI/CD pipeline removes the subjectivity and scales infinitely; enforcement++.

DETERMINISTIC RULE ENFORCEMENT VERSES DESIGN "ART"

I'll concede that automated enforcement scales. However, hammers are blunt instruments. Some deterministic rules, like not allowing a body payload on a GET request, or returning a 200 status code with an embedded error object response, are easy to test for. Automate these away from your organization's designs.

However, a design that faithfully adheres to the HTTP convention does note immediately qualify as intuitive, powerful, or solving a stakeholder need. The API architectural style is about reducing communication overhead between producer and integrator. The value of an API style guide, when applied, is a set of affordances that minimize the weirdness that must be grokked.

Naming, types, and descriptions are a big part of communicating these affordances. They also happen to be challenging to automate. Take, for example, these recommended element properties from my area of practice:

CHARACTERISTIC DETAILS EXAMPLE Context Detailed business context explaining what the data stands for and its expected usage. "FICO score takes into account the payment history, level of indebtedness, types of credit used, and length of credit history." Disambiguation Explains terms not commonly used. "Field refers to the date that the LK32K system processed the transaction. LK32K is used for payment by the customer." Interrelationship Defines if there is an important interrelationship with other available data in the same structure. "Source account status code and source purge indicator are referenced together for obtaining the correct status of the account." Values, Range, or Examples Proves insight into the range or bounded set of values possible. "Valid FICO scores are between 300 and 850. A FICO score less than 300 or greater than 850 is invalid. Negative numbers should never be used." Data Sourcing Where data comes from or how it is generated. "The FICO score is provided by Equifax." Reference/Notes Provides links to additional documentation. "For more information on US Bureaues, please see https://example.com"

In his conference talk, Michael Amundsen argued that this level of design aspiration strays too far into craftsman territory. He's a persistent advocate for a mechanistic approach; rather than hoping for people to get better at expression the idea is to remove the need for human comprehension all together. To enable the next logarithmic jump in communication volume, the thinking goes, machines should talk to machines at machines' speed.

That's not where the industry is, however. Meeting people where they are means putting a human in the loop. Putting people in governance roles then means, subsequently, they're asked to navigate human motivation.

MOTIVATION TUNNEL VISION

In change management, there's the metaphor of "sticks and carrots". Together, they represent soft and hard power governance that I've written about in the past. Enforcement, either by people or process, is a stick because there is a threat of punishment. Even when well meaning, sticks are demoralizing because they take agency from the actors in a system.

To avoid the downside of sticks, some companies attempt to employ carrots. Carrots are rewards for performing a desired behavior. They may not stand on their own; sometimes these carrots are used in conjunction with sticks.

Regardless of which is used, both sticks and carrots address address developer motivation through the manipulation of incentives. However, after years of wrestling digital transformation adoption, I've come to see that enforcement and rewards aren't the only tools in the toolbox. In fact, according to BJ Fogg's Tiny Habits book, motivation is one of the most fickle levers to pull in service of a change initiative like API style adoption.

Tiny Habits is a fantastic book, both for organizations as well as personal development. I'd encourage people to read the whole thing. But to summarize:

• Organizational change is a result of one or more behavioral changes.
• Behavior change happens when ability, motivation, and a prompt are each present.
• Motivation gets all the focus in a change initiative, even though it is the most fickle (how many gym memberships are still being used on February 1st?).
• When creating change, start with the prompts, then improve developer ability, and then address motivation.

"Hold on," I can hear you say, "I just want all datetimes in our company's APIs to use ISO 8601 consistently. You're talking about prompts and carrots and crap?"

Yes, I started with API style guides. However, the bridge I'm building is the next decade's growth industry - successful software change regardless of whether it is API, cloud, devops, related.

SOCIOTECHNICAL ARCHITECTS AS COMMUNITY OF PRACTICE LEADS

Sources vary, but 80%+ of digital transformation efforts fail. Traditional, top-down approaches don't work in a majority of cases. Enforcement of API styles in OpenAPI descriptions can be demoralizing. Offering rewards may net participation when it is convenient, but the sugar rush of external motivation doesn't last.

Sociotechnical architects place just as much emphasis on the organizing system (teams) building a solution as traditional architecture considers technical systems. Communities of practice are groups of people who share a concern, a set of problems, or a passion about a topic. They deepen their knowledge and expertise by interacting across organizational boundaries. Responsibility and authority are shared. Those most creating and co-evolving governance are those directly impacted by it.

These communities, lead by recognized sociotechnical architects, create high energy cycles: high energy leads to high effectiveness, leading to higher recognition in the organization, which attracts other people with high commitment. These virtuous feedback loops drive design improvement.

As change attractor, communities of practice, specifically for API style adoption, is certainly a road less traveled. However, after being at this for years, I'm confident we need to push ourselves to evaluate other models. I firmly believe it is better to build a community of passionate participants rather than police an authoritarian state.

Is this useful to your situation? Do you want to hear more about this? Reach out; I'd love to chat.

MILESTONES

• Postman published its 2020 State of API Report. (does this warrant a bigger conversation???). The biggest conclusion? "Close to half of respondents stated that investment of time and resources into APIs will increase over the next 12 months, while another third stated that investments into APIs will stay the same, despite economic uncertainty.".
• Shopify support staff used an internal API to steal customer data. Goes to show securing internal APIs is as important as external ones.
• The non-profit Sunlight Foundation has closed down. The group advocated for open government and, in the process, created a number of APIs. Thankfully, many of those APIs (and supporting tools) appear to have been adopted by others.
• Noyo raises $12.5 million to continue building its health insurance API business.
• Stoplight Studio Desktop 2.0 has been released.

WRAPPING UP

Whew! This was a long one. Thanks if you've stuck with things this far. And thanks to the Patreons who inspired this particular newsletter.

Till next time,

Matthew @libel_vox and matthewreinbold.com