4 systems thinking lessons for APIs

Systems thinking for APIs

Hope: He’s in the system.
Luis: I’m in the system?
Dave: You’re in the system!
Luis: The system?
Hank: We’re doomed.

– Ant Man, 2015

“System” is one of the most overused and overloaded terms in technology. Data is stored in “the system”. Applications run on “the system”. Operators manage a distributed “system”. It has become so ingrained in the IT vernacular that we don’t even think about its meaning. But recently–especially with the rise of the microservices movement–the software engineering community has become fascinated with complex systems in general. If you attend a software conference these days, you’re likely to hear a talk on ant colonies, bird murmurations, or blood flow. (All great talks, by the way…) As the software engineering industry matures, there is an increasing recognition that systems thinking is a profoundly important concept.

The study of complex systems is older than computers, and encompasses the fields of systems theory, systems engineering, cybernetics, and the aforementioned systems thinking. It can be daunting to get started, but I recommend two books that are both foundational and practical. Thinking in Systems: A Primer, by Donella Meadows, is an introduction to the concepts and practices of systems thinking. The Art of Systems Architecting, by Eberhardt Rechtin and Mark Maier–a book I referred to in my last post, API products, not projects–outlines the systems engineering perspective and applies it to a wide range of systems types, including software-centered systems. Both books have innumerable lessons on complex systems that can be applied to software, but here I’d like to focus on the lessons that apply specifically to the use of APIs.

API systems lesson #1: Flow is good, feedback is better.

The first chapter of Meadows’ book contains the primitives of system structure: stocks–quantities of things that go up and down–and flows–both the sources of change in stocks as well as their connectors. In the world of integrated software, we might view applications as stocks of data and logic, and the APIs that connect them as flows. Much of the design work in software architecture features boxes and arrows that mimic the “stock and flow” diagrams in the systems world.

However, the source of elegance in systems, according to Meadows, are the mechanisms by which inflows and outflows can be monitored in order to regulate stocks: feedback loops. Meadows describes feedback loops as “how the system runs itself,” and states that “system thinkers see the world as a collection of ‘feedback processes.’” Feedback significantly increases the capability of the system.

What does feedback mean in an API context? APIs can be valuable simply by providing access to data or services in a consumable manner. However, one of the value points APIs offer that is frequently overlooked is their ability to provide insight into consumer behavior. As more products and services become digitized, APIs offer the providing organization the opportunity to observe searches, abandoned purchases, and other activities that would have been invisible to them in the pre-digital paradigm. This information creates a more detailed and immediate digital feedback loop that helps API providers adjust their strategies and prioritize their roadmaps with greater certainty.

API systems lesson #2: APIs will help you understand the system.

Most large organizations already have complex systems of interconnected applications and data. Without a normalized approach to connecting the system’s components, it can be difficult to even find the interfaces. By standardizing on API-led connectivity, it becomes possible to see the system as a whole, not just its resident applications and other components. In the words of Rechtin and Maier, interfaces “distinguish a system from its components.” Observability of the system helps you understand its structure. According to Meadows, “structure is the key to understanding not just what is happening, but why.”

Compare the following two crudely drawn diagrams of application connectivity in an anonymous organization:


Regardless of any changes in arrows, the diagram featuring the articulated APIs gives you a better sense of what functionality this system actually provides. Assisting the comprehension of the system improves its manageability, governability, and–as we will see next–evolvability.

“Make a system evolvable by paying attention to the interfaces.”

– The Art of Systems Architecting, by Eberhardt Rechtin and Mark Maier

API systems lesson #3: APIs will help the system evolve.

Since, as Rechtin and Maeir put it, “technology changes perceptions of what is possible,” change will always be a constant in software systems. They go further on this point, stating “when a system is expected to undergo extensive evolution after deployment, it is usually more important that the system be easily evolvable than that it be exactly correct at first deployment.” One of the great insights of Meadows’ book is her definition of “leverage points—places in the system where a small change could lead to a large shift in behavior.” By their nature, complex systems are self-regulating and stubborn. To make effective, lasting changes, leverage points must be exploited. Rechtin and Maier’s book contains several heuristics–experience-based guidelines–that help in the design and management of systems. One of these quoted throughout their book is, “The greatest leverage in system architecting is at the interfaces.” APIs, therefore, are a point of high leverage for change in a software system.

Both books talk about system hierarchies and the importance of “stable intermediate forms”–independent subsystems that provide standalone functionality–within the hierarchy as the only means of accelerating system evolution. Both books also give similar guidance on how to structure the system’s hierarchy to maximum effect. Meadows notes that “systems relationships within each subsystem are denser and stronger than relationships between subsystems,” while Rechtin and Maier encourage system designers to “choose components so that each can be implemented independently of the internal implementation of all others.” When systems are partitioned effectively into stable intermediate forms, it “reduce[s] the amount of information that any part of the system has to keep track of” (Meadows). Conversely, according to Rechtin and Maier, “poor aggregation and partitioning during development can increase complexity.”

As reusable conduits for application connectivity, APIs are stable intermediate forms. When APIs are designed to offer maximum value to their consumers, maximum cohesion within the functions their underlying services provide, and minimal leakage of implementation details, they will facilitate maximum evolvability of the system within which they reside.

API systems lesson #4: View the API-based system as a network, not a platform.

In their chapter on “Software and information technology systems,” Rechtin and Maier note a distinction between the hierarchies of hardware systems–where subsystems are contained within upper-level supersystems–software systems are “typically composed in a layered design,” without this constraint of containment. There is a natural order to the layers in a software system based on the pattern of interaction, but any component in the system can theoretically call any component in an adjacent layer.

Software architectures are evolving away from statically-tiered horizontal capabilities to fractally-layered, API-enabled, business-aligned services. In an API-based architecture, the layer adjacency constraint doesn’t even need to exist. With this perspective, it helps to use a network mindset when analyzing such systems. Rather than think about application stacks, you can visualize the system’s topology. This allows you to focus on the interactions between components–the highest point of system leverage–without getting stuck in the weeds of the components’ underlying implementations.

Another useful network analogy in working with complex software systems is the concept of “planes.” Much like a city plan contains transportation, zoning, police jurisdictions, and water systems, a software system can be analyzed from several perspectives. What is the flow of business data? What are the different availability and security zones? Rechtin and Maier anticipate “As we move into complex, information-centric systems we will have to accept the existence of many views, each representing different concerns, and each targeted at a different stakeholder audience.” It is both acceptable and necessary to analyze the same system along these different dimensions. According to Meadows, “Where to draw a boundary around a system depends on the purpose of the discussion.”

The network world confronted this issue of multiple views for different purposes by distinguishing the “data plane” — the space in the network where business data travels — from the “control plane” — the space where information flows regarding the functioning of the network itself. The control plane splits further into data related to routing, security, traffic control, component health, and so on. Software systems connected by APIs–appropriately thought of as application networks–have similar planes. There are business-aligned APIs that constitute the data plane of the application network, and administrative APIs–facilitating automation, policy enforcement, etc–that make up the control plane. Using the network mental model is helpful in understanding the structure of API-based systems and in applying some of its timeworn approaches.

Join the conversation at O’Reilly Software Architecture conference

That’s a lot to chew on, but I hope these lessons are useful in your deployment of APIs, and I strongly encourage you to read both books. If you would like to hear more about how systems thinking can be applied to software architecture in general, I will be conducting a workshop and presenting a talk at the O’Reilly Software Architecture in San Jose, which runs from June 10 to June 13. Hope to see you there! I promise there won’t be any ants crawling around the room.

Special thanks to Mike Amundsen, Ronnie Mitra, Holger Reinhardt, Irakli Nadareishvili, Erik Wilde, and Mehdi Medjaoui for the discussions on complex systems over the years, and to the anonymous @archithinkery Twitter handle that recommended the Rechtin/Maier book.

We'd love to hear your opinion on this post

One Response to “4 systems thinking lessons for APIs”

  1. Brilliant article! We have seen that most of the integration architects burn themselves out by the time they reach process APIs. Thats when they don’t realise that they are more than half way through and out of the times leave the architecture devoid of Experience APIs. The “digital transformation” organizational silos don’t help much either!

    As you rightly mentioned, the integration architects (and the business owners) need to see API system as network and not just a platform!