I presented “APIs are Arrangements of Power” at the 2020 APIDays Interface conference. It was my first virtual conference and a very different experience. How I prepared for that context is a different article. For now, the slides and script are below.


Title Slide

(Office Photo by Ali Yahya on Unsplash)

I am Matthew Reinbold

Hello, everyone. I hope that you and yours are healthy and safe during this interesting time. If there is a sliver of a silver lining to all of this, I think it’s doing things like this gives some extra context and insight into the type of people you might otherwise only interact with online.

Welcome to my workshop and creative space. My name is Matthew Reinbold. As was mentioned, I work for Capital One. I am the Director of the Platform Services Center of Excellence. That’s a lot of words. It means that my team and I work with our 9000+ developers on thousands of APIs that answer 3.5 billion calls a day. It is a large ecosystem that we steward. We’re also increasingly involved with things like standards and processes and training around data transformation and event streaming. It is a role that cuts across the entire company and collaborates with numerous disciplines.

I also write Net API Notes, a regular, weekly email newsletter that just celebrated five years. There I chronicle the comings and going of an industry in flux. Talking about one API, or even a handful is one thing. The challenge of managing thousands is something different. I’ve seen what it takes to go from API theory to practice.

Where to find me, along with a hashtag for social media, is in the footer of each slide so we can continue the conversation even after my time is up here.

Agenda

There’s plenty of blog posts, videos, and presentations - some at this very conference - that go DEEP on technical and tactical aspects of delivering APIs. That is useful. However, many of us who have been involved in the space for a while have realized that just cargo-culting someone else’s tech stack isn’t enough to guarantee success. Just because you’ve implemented all of Netflix’s open-source projects or replicated Amazon’s cloud infrastructure doesn’t mean you’re going to be successful in delivering business value.

Why is that?

It is because APIs are more than just technology. It has so much more to do with how an API strategy manifests within the people responsible for carrying it out.

This talk is for anyone that cares about creating better, more well-designed software - not just APIs. To do that, we’re going to have to architect people, not only machines. And, in the process, perhaps redefine your expectations of the role API governance.

Part 1: The Power of Organizations on Architecture

Conway's Law

In 1968, Melvin Conway published a paper entitled “How do Committees Invent?”. He proposed that the way that an organization was arranged directly and dramatically affects how software is made.

That early anecdotal observation was later supported by quantitative research. It stated that:

  • Organizational distribution and product modularity are correlated
  • Products really do end up looking like the teams that create them

Suppose that a company has two development teams that rarely talked with one another: one supporting the warehouse and another supporting the back office. If you set out on an API journey, Conway’s Law predicts that the resulting architecture from those teams would consist of two APIs: one for the warehouse, one for the back office. This despite the fact an external 3rd party wishes to integrate with your single company, not your org chart parts.

Organizational Structure Impacts Code Quality

But the organizational arrangement doesn’t just affect modularity.

  • It turns out that organizational complexity is also the greatest determining factor for how buggy a piece of code is.
  • The more complex the organization is (due, in part, to how removed decision-makers are from implementors) the worse the code is.

(The Microsoft Research Study mentioned here.)

Organizational Structure Impacts Delivery Performance

Accelerate: Building and Scaling High Performing Technology Organizations, published in 2018, cited organization arrangement as a key contributor to achieving delivery performance as well as for whether the engineering organization can scale.

“If we achieve a loosely-coupled, well-encapsulated architecture with an organizational structure to match we can achieve better delivery performance… and substantially grow the size of the engineering organization and increase product lineraly.”

Organizational Structure Impacts Morale

Team Topologies is another book dedicated to organizational arrangements. It also happens to be the best API book that I’ve read thus far this year, despite not marketing itself as an API book. The authors agree that it isn’t just getting the technology right. Designing the organization that utilizes that technology is just as important.

“Never before has explicit sociotechnical design been so important.”

I say more on that $5 word, “sociotechnical”, in a few minutes.

Organizational Structure Accounts for 90 or 95 Percent of Performance

W. Edwards Deming was an American engineer and management consultant. He is often credited as one of the inspirations for the Japanese post-war economic miracle of the 1950s. When it came to organizational arrangements, Deming said:

“The fact is that the system that people work in and the interaction with people may account for 90 or 95 percent of performance.”

When I talk about cargo-culting, when I talk about those teams that take everything that Netflix has done and jam it into production, when I talk about turning on every toggle in the AWS interface in the hopes of achieving the same kind of success I talk about failure to acknowledge what Deming says. It is one thing to imitate the technology. However, that is such a small aspect of what it takes to deliver value.

Designing better APIs means first recognizing, then addressing Conway’s Law.

Three Ways Conway's Law Affects API Governance

I want this presentation to be additive. I want it to build on stuff that is already out there. That does mean that it comes with a bit of homework if you’re interested in learning more.

At the 2016 API Strat Conference, I presented “3 Ways Conway’s Law Affects API Governance”. In that talk I gave three different ways the organizational makeup affects the API design. If you are passionate about this stuff, I encourage you to seek that out and learn how hierarchy, geographical organization, and 3rd party lines of communication end up changing the API design in specific ways.

buffer's story is one of organizational arrangement

I want to provide at least one new example, as well. That comes from Buffer. Buffer is a social network management platform. In late 2015, Buffer acquired Respondly, software that enabled social media teams to respond to customers. Buffer’s technical leadership now found themselves managing two monolith architectures. These two products, Buffer and Respondly, were not connected in any way. Despite offering complimentary products, the organization’s arrangement meant there were significant challenges to delivering business value. The organizational communication structure was negatively impacting the ability to provide obvious customer value that spanned both offerings.

In March 2017, Buffer re-imagined itself as a platform that would support multiple complementary products. The technical team realigned themselves into groups responsible for core functionalities: billing, sessions, centralized storage of a user’s social media account connections. On top of that they reorganized both their architecture and additional teams around customer’s jobs-to-be-done: Publish, Reply, and Analyze.

To deliver the most value to the consumer, Buffer needed to change its architecture, which necessitated a change to its organization.

(The buffer story comes from this Increment.com article)

Part 2: The Power of Architectures On Organizations

Developers Are Doing Just As Much Work in Building Companies As Code

By this point, I hope I’ve convinced you that the arrangement of the organization, specifically how it communicates, impacts how software is made.

But can we go the other way? Can the architecture drive organizational change? Or does it always have to start with the organization?

Vicki Boykis is a data scientist and technology essayist. In her June 6th newsletter, she wrote:

“Something happened in the last 30 years where developers transformed from some nerds sitting in the company’s basement, to the driving force of the company itself. Developers now have a lot of power, and, consequently, are doing just as much work in building companies as in building the code.”

Feng shui is a design practice that attempts to use the arrangement of objects to harmonize people in their surroundings. Likewise, APIs are an arrangement of power. Designed with purpose, the arrangements have the power to shape organizations.

Sociotechnical Systems Optimize Both People and Technology

Designing arrangements with purpose is not a new concept. The relationship between people and systems has been studied for some time. The field of Sociotechnical Systems Engineering dates back to World War II. The word “sociotechnical”, which I mentioned earlier, refers to the interrelatedness of an organization’s social and technical aspects. It seeks to optimize both the people and machine in order to improve performance and work-life quality.

Taking a sociotechnical system approach, an API practice attempts to identify the systematic power arrangements that exist within an organization.

As explained earlier, these factors can have an enormous impact on the software produced. And yet, if it is as powerful as I suggest, why do we so rarely see this?

You Can't Out-Tool a People Problem

If I were to speculate, I would guess that the messy, complicated work with people is something outside of most engineer’s training? Or, perhaps, it is something that is derisively regulated to “the humanities”. Or maybe it is because people are used to thinking about individual pieces, and rarely of a system as a whole.

Whatever the reasons, given the power that organizational arrangements have to deliver quality code, that is a shame. It is also a vast, untapped area of improvement.

Donella Meadows was one of the foremost system thinkers. In her both her educational work and book, “Thinking in Systems”, she repeatedly impressed the importance of communication above all else.

“The scarcest resource is not oil, metals, clean air, capital, labour, or technology. It is our willingness to listen to each other and learn from each other and to seek the truth rather than seek to be right.”

Ultimately, this is why cargo-culting fails. All the importing of another company’s open-source toolkits, their deployment playbooks, and their tech does nothing to address the interpersonal-communication of the groups implementing them. Said another way, it doesn’t matter how silver the bullet is if the gun continues to misfire.

Part 3: The Inverse Conway Maneuver

Using architecture as a beachhead for changing the organization has a name. The Inverse Conway Maneuver is where the architectural needs required for consistent, cohesive design and fast flow are considered first. The organization, subsequently, is built around that.

(Photo by Bob Fisher on Unsplash)

Change Happens

Change happens all the time, even to organizational arrangements. Sometimes it is not the way we want it. Sometimes it is not at our preferred pace. But change occurs in ways both tiny and epic.

The apocryphal story of the Bezos memo is one such example. As the story goes, one day in 2003, Jeff Bezos required that everyone create API interfaces for their services. Anyone who didn’t do so would be fired. If that sounds harsh, it is ok; the email ended with Bezos wishing the recipient a lovely day. Kind of a passive-aggressive thing going on there, but it seems to work for them.

That change in how the organization communicated among itself set the stage for AWS. The Bezos memo stated that the company needed to change its architecture to take the organization to where it needs to go.

However, as head of Amazon, Jeff Bezos had the hierarchical power to declare that kind of change. Where do you begin if you’re somewhere else other than the top within the org?

As you might expect, this is a big topic, and there is only so much I can cover in a 20-minute conversation. The road you will travel is dependent on your context. However, I want to briefly cover two useful approaches in the time we have left. They are (1) Shrinking the Change and (2) Scripting the Critical Moves.

(Origins of the Bezos Memo are available online)

Shrink the Change

The two techniques I’m covering are from a book I have pictured here, called Switch. I highly recommend it not just for these two approaches but also for the number of illustrative cases it presents.

The first technique is shrinking the change. Upending organizational arrangements might be necessary. But starting with an intent that large will be met with proportional resistance.

Instead, shrink the change and, in the process, you’ll shrink the likelihood that people will say no.

  • Can’t change an organization? Start with your line of business.
  • Can’t change your line of business? Start with your program.
  • Can’t change your program? Start with your team.
  • Can’t change your team arrangement? Start with how (and whom) you communicate.

So much of this is about the complexity of our daily communication. How regularly do the API implementation teams talk with the primary stakeholders? Are their intermediaries involved? Do groups talk past each other while emailing attachments? Are the same people always at the table? Or are new pathways being forged by the purposeful and ongoing discovery on your part? Are you building relationships in places where none existed before, are new opportunities presenting themselves?

Even if through informal conversations, changing access to information is a precursor to those affordances being codified in an interface. It is also the first step to organizational change. It can also be as simple as buying someone a coffee or (these days) having a video meet-n-greet.

Script the Critical Moves

Another idea is to script the critical moves.

Many people, especially during a global pandemic, don’t have a tremendous amount of bandwidth for the unknown. We are dealing with unprecedented, low-level, and persistent stresses. The ambiguity of the unknown saps our energy and lessens the likelihood of new pursuits. The appetite for the potentially ambiguous just isn’t there right now.

In this environment, providing the explicit, incremental steps for change may be necessary. A level of prescriptive detail lightens the lift for, otherwise, distracted, distraught, and disengaged teams.

One of the things I’m currently working on with James Higginbotham is a prescriptive process for teams to design bounded contexts. There is an ocean of tips and techniques out there for how to do this already. However, right now, for our audience, telling people to boil that body of water to find something pure that works for them is too much. We need to script the critical moves.

Maybe there are alternatives to what is in the prescriptive plan. Perhaps some of those alternatives might be better in certain contexts. For those that don’t have the bandwidth for that exploration, however, we’re providing a roadmap to get them moving. We’re attempting to make getting started as easy as possible. We’re scripting the critical moves.

I also mentioned the Team Topology book earlier. I appreciated this book because it takes an infinite number of team arrangements and asserts four specific, followable team types. There may be other arrangements. Your mileage may vary. However, for those looking for an example organizational structures, the Team Topology book is also an example of scripted critical moves.

Git Gud at the Peoples

Let’s get real for a moment.

I know changing organizations may not have been what you signed up for when you assumed responsibility for your APIs. I suspect that the reason you chose software development was the hard certainty of 1s and 0s, rather than swishy, unpredictable nature of the people around you.

However, there is a problem. We spend thousands of dollars on ongoing training. We accumulate hours and hours of precious time getting certified and accredited. Back when it was still a thing, we even traveled across continents to learn the esoteric ins and outs from others. Yet, when it comes to interpersonal communication, the thing that we do every day, we can’t be bothered to Google improvements?

That’s wrong.

We deal with people. We spend our time and budget optimizing machines, but it is the people that matter. It is the people that determine the success or failure of our efforts.

Working with people to build a better organizational structure is a skill like any other. It can be learned, but only when our API designers and architects stop ending at the interface and start entrepreneuring sociotechnical relationships. Your organization’s ability to deliver business value reliably, scalably, in the face of accelerating change depends on it.

Change is not Kubernetes. Change is not a service mesh. Change happens with people. That is why it is time to git gud on the peoples.

(Photo by Nicholas Green on Unsplash)

Part 4: Conclusion

API Governance is a Sociotechnical Function

When it comes to software systems, many conclude that API governance is a checklist, or a set of rules that must be applied. While the enforcement of common practice on something like an OpenAPI description of intent might be a tactic of governance, it is not a strategy.

Governance broadly refers to who decides what is in a platform’s ecosystem. Said more generally, governance is a framework for how we choose to co-exist. Checking for naming inconsistencies and implementation detail leakage out through the interface is one thing. I’m challenging you to get to a higher level. That level is to be a organizational designer.

The invitation to co-create these arrangements changes the way information flows in a company. Changing the way communication flows is a precursor for changing behavior, and changing behavior is a precursor for changing the organization itself.

The book “Platform Ecosystems: Aligning Architecture, Governance, and Strategy” has a number of profound statements on this area. The chief one is:

“The architecture of a platform is inseparable from how it ought to be governed.”

That is the real power of API governance.

Further Reading

There are many books in this space. If you are interested in work being done around organizational arrangements and their effect on value creation check out:

  • Accelerate
  • Team Topologies
  • Thinking in Systems

There is also a fair amount written on change management. Many of them are related to individuals but the ones that I’ve listed here can also apply to organizations.

On Change

  • Switch: How to Change Things When Change is Hard
  • Agendashift: Outcome-Orientated Change and Continuous Transformation
  • More Fearless Change: Strategies for Making Your Ideas Happen
  • Tiny Habits
  • Blue Ocean Strategy (the latter third)

Thank You for Your Attention

That’s it! My name is Matthew Reinbold. I hope you’re safe. I hope you’re healthy. And I hope to talk with you again soon.