Some of my most rewarding conversations in my professional career are when I coach folks on their emerging API governance needs. A common myth is that companies must settle for one extreme decision-making structure or the other regarding governance. Either they grant API teams full autonomy and suffer from the fragmentation and associated overhead it brings. Or they gain alignment and consistency through centralized oversight and heavy bureaucratic processes while losing innovation opportunities.

Unquestionably, anything done to an extreme can create negative consequences. However, in my experience, too many companies only see a total commitment to one position or another as their only option. What companies need, in reality, is a blending of the two approaches.

How do we find the Goldilocks (the “just right”) amount of governance? With a polarity map.

(Re)Introducing the Polarity Map

Fig 1: An Empty Polarity Map; I've Made A Google Jamboard Template Available based on the example from UXMastery.

Ruth Malan’s Organizational Design Masterclass introduced me to polarity mapping. A polarity map recognizes there are benefits and unintended consequences with each extreme. It encourages participants to describe these in detail. Once we’ve identified benefits, we then discuss activities to achieve these desirable traits in our system. After that, we can define a series of measurable indicators. The purpose of these metrics is to signal when we’ve overcorrected and risk unbalancing the system.

We might use polarity maps for a variety of “versus” articles popular software architecture:

  • Build versus Buy
  • Microservice versus Monolithic Architectures
  • Synchronous versus Asynchronous
  • Batch versus Real-Time
  • Testing versus Debugging
  • API-Design First versus API-Code First
  • Tabs versus Spaces (joking, kinda)

Polarity maps help explain a phenomenon I observed in previous roles: the “pendulum effect”. If we begin to fill in the map according to the “decentralized versus centralized” API governance, as I described in the beginning, the map looks something like this:

Fig 2: A Beginning Polarity Map for Centralized Versus Decentralized Governance

Most organizations start API governance in the upper left of the quadrant, “decentralized”: individual API teams have nearly total decision-making autonomy. While this is efficient initially, the problems with this model become more apparent as the size of the API ecosystem grows. The map represents this change with the downward arrow leading to the lower left quadrant.

As the negatives accrue, support for the opposite pole, or “centralization”, grows. The organization seeks the benefits of the upper right quadrant. This change works, for a while, until the overcorrection creates its adverse effects. If we continue to follow the arrow’s path, we end up in the lower right area. When the downsides reach a critical mass, the organization moves back toward decentralized decision-making and repeats the process.

By putting both extremes on a single plot, we can demonstrate benefits to both sides. Moreover, in establishing the oscillation between sides, we can make a case that adopting one or the other is not an argument to be won but a set of properties to balance.

Getting Started With A Sample Map

To illustrate the process, let’s walk through an example polarity map that shows what many burgeoning API ecosystems struggle with: *do we promote centralized or decentralized API management?

When doing a polarity map, it is essential to remember that each will be different; every company has unique needs, people, goals, and available resources that impact what is listed. YMMV.

However, based on my own experience, a set of benefits and unintended consequences for both sides might look something like this:

Fig 3: An API Governance Polarity Map With Example Benefits and Unintended Consequences

Defining Action Steps and Early Warnings

Defining benefits and unintended consequences is a significant first step. Talking through effects and their placement on the map is beneficial for building organizational or API leadership team alignment. Where things get truly useful is going to the next level and identifying action steps and early warnings.

Fig 4: A Polarity Map with Action Steps and Early Warnings Added

Action Steps are how we will gain or maintain the positive results from focusing on a given pole.

Early Warnings are quantifiable indicators to signal when a system is straying into the downside of a pole.

Suppose we want to take actions to promote the positive aspects of centralization (the upper right: “visibility”, “predictability”, “consistency”, etc.). Action may include:

  • Documenting API standard operating procedures (including, but not limited to, style guides, production environment readiness requirements, architectural decision records for changes, etc.)
  • Creating compensation or recognition structures for teams demonstrating API excellence
  • Forging communication channels to both promote the best work as well as solicit feedback for further refinement

Early warnings for the centralized side of the map may be more challenging to define but not impossible. There could be a problem if there’s a growing clamor of teams waiting on the centralized group for a decision, or a noticeable uptick in meetings to reconcile a tricky edge case. Identify which areas are of most concern for your organization, identify how to quantify changes, and continue to iterate until you have something actionable.

The left side is left as an exercise for the reader.

Conclusion

Polarities involve two equally valid and necessary points of view or truths. Despite how we usually think of them, polarities are interdependent pairs that need each other to maintain and gain performance.

A polarity map is a tool that API leaders can use to understand where they are in the system and accentuate positive aspects of both worlds. When it comes to API ecosystems, polarity maps suggest that centralized or decentralized decision-making is not final governance destinations but part of a whole to be managed.