The Favela vs the Planned Community

When speaking about the entire API life-cycle, much of the terminology is muddy. To me, API Management are those things concerned with the day-to-day operation of an API or API ecosystem. These are things like self-service documentation, monitoring, access enforcement, and request throttling. I define API Governance as those processes which shape and inform the way APIs are made in conjunction with other APIs. It is the planning that is concerned with the health of entire ecosystems, not a single implementation.

There's not a whole lot of governance required when a company has one API. It is what it is. The need for a larger approach to the design and building of APIs is warranted when we consider multiple APIs, as is the case with microservices. With this architectural pattern a company may have dozens, if not hundreds, of exposed APIs. Here applications may no longer have point-to-point integrations with the APIs they're dependent on. Instead, interactions are the result of numerous APIs being composed into new experiences. These experiences are enabled from having a neighborhood of coherent, consistent APIs to draw from.

Picture a favela, or Brazilian shantytown. Each building successfully fills the role of a house. It provides shelter and security. Like an API, it is encapsulated and enjoys a certain level of cohesion. If all we were concerned about was the functional requirement to have lots of houses there we can look at the resulting hillside patchwork and call it a day.

A Brazilian Favela. Photo by Armando Lobos. Used under Creative Commons license.

But expecting a new product to navigate this is unrealistic; those new to this environment will quickly be overwhelmed and lost. There has been no thought to things like accessibility or navigability because there was no coordinated vision for the holistic environment. There was no HOA or community planning. We lack a larger vision for the neighborhood.

Planned Community. Photo by Dan Reed. Used under a Creative Commons license.

This vision is not the role for Quality Engineering (QA). QA is a separate discipline devoted to ensuring that the functional requirements of effort, or the API, are met. QA, using our neighborhood metaphor, is more akin to building inspectors. They ensure the house is structurally sound, adheres to the original plan, and won't inadvertently cause harm. That is a vital role, but one focused on the house, not the neighborhood.

API Governance still requires each API to fulfill it's functional requirements; API developers still are the construction crews tasked with building houses. However, API Governance has a responsibility to ensure non-functional requirements are also accounted for. These are the API equivalents of access for emergency personnel, edifying amenities like pools and green-spaces, and consistent navigation throughout. There are lots of places that meet the basic expectations for shelter. But how desirable is the neighborhood?

At the recent Capital One API Summit, Irakli Nadareishvili was adamant that centralized planning is a mistake, whether for economies (ala Communism) or microservices. I agree that overly onerous bureaucracies, acting as gatekeeper between development and deployment, will sap the innovation and agility from a system. The inability to respond to new business opportunities (or threats) is a bad thing. However, the wild west is also an untenable model. A constantly changing landscape with no structure or coherence is not a place I want to build, either.

API Governance is a tricky balancing act. But, ultimately, it is necessary for creating appealing API neighborhoods.

Update: This piece generated a fair amount of discussion. I've attempted to capture some of it.