Struggling to Manage API Program Complexity? Try this model instead.

Us API old-timers can recall when creating a REST-ish API was not an apparent architectural choice; I still have the scars from one particularly heated JavaServer Faces [JSF] debate. Getting together for conferences and meetups was as much about evangelizing why APIs were important as, if not more, than how to get work done. Now, if you go into any modern IT shop, shaking a network cable without hitting an API call is hard. Whether it is cloud configuration and management, 3rd party services, or serving the business logic itself APIs, are just part of how work now works.

But with this new, ubiquitous reality comes new challenges. In this edition of Net API Notes, I'll share a way to organize the universe of competing API concerns into an approachable, concise model. I'll share a handful of stories on how this model has helped real-life enterprise challenges and end by dispelling a few myths about one of the most misunderstood phrases in corporate culture: software governance (which includes APIs).

API Governance Can Be Good, Actually

The Goal Should Be Alignment with Autonomy

Organizations didn't start out having to herd dozens, if not hundreds (thousands?) of cats. The autonomy provided by an API architecture, tried by a few, was successful and was quickly adopted by others. But with this increased abundance of autonomy comes incoherence, as depicted on the left of the following image: lots of things moving at different speeds and in different directions.

A typical response among leadership, when they recognize they have a problem, is to centralize all the things. Whether that is establishing a CENTER OF EXCELLENCE, the more mealy-mouthed CENTER OF ENABLEMENT, or some other variation, the resulting organization and process risks too much convergence, reducing variety and innovation. While the simplest to understand, these "command-and-control" approaches to "stop the bad thing from happening" are often a poor match for modern software needs. Or, worse, they'll marshall someone to draft an API design standards doc (with associated linting ruleset) and toss it over the cubicle wall, hoping that token automation will create cultural change (spoiler: it won't).

Both development teams and the organizations they work for ultimately want the situation on the right: autonomous teams whose efforts are aligned to serve the business needs - less cats to be herded at great conflict but a flock of birds or a school of fish moving in synchronicity.

While the recognition and enthusiasm for the work to be done is a great start, the ability to create desired outcomes without formal, direct authority requires additional training and skill development. In the same way you wouldn't expect to win a race without training for it, you shouldn't attempt software governance (in general) or API governance (specifically) without first researching what previously has shown to be successful.

Thankfully, for groups willing to put in the effort and know where to look, there's a wealth of fantastic resources that not only make software governance success more likely but help avoid common pitfalls. Two excellent resources that not only echoed powerfully with my personal experiences but also provided additional insights are:

• IT Governance: How Top Performers Manage IT Decision Rights for Superior Results (2004) by Peter Weill and Jeanne W. Ross
• Platform Ecosystems: Aligning Architecture, Governance, and Strategy (2013) by Amrit Tiwana

There's an incredible amount in both books of interest to those looking to create coordinated movement in an organization. However, the most impactful lesson for me was how they crystalized three of the most common dimensions of software governance.

Software Governance Has Three Dimensions

Those responsible for any software platform in an organization enjoy a unique position. They do not see one or two APIs but all the APIs in a given space. As such, they are the most familiar with the problems caused by ad-hoc and incoherent approaches. As owners of an important piece of shared infrastructure, they are also in a position to do something about that inconsistency.

To start thinking about the levers at their disposal, platform owners should group their efforts into three broad areas:

• Decision Rights Partitioning, or the division of authority and responsibilities between the platform owner and API developers
• The Control Portfolio, or the collection of mechanisms through which the platform owner exercises control over developers, including the ability to accept or reject APIs for inclusion on the platform
• Pricing and Subsidies, or how resources will be divvied up between a platform owner and app developers, and what behavior gets subsidized

Each area interacts with the others while bringing something unique to the table. Let's break down each of these dimensions in more detail.

Decision Rights Partitioning

The first dimension is decision rights partitioning, or deciding whose responsibility it is to make a given decision. A decision right can reside with the platform owner and centralized authority, like a Center of Excellence. We call that a centralization of a decision right. Or the decision can live with an API development team, which we'd call a decentralized (or federated) decision.

Examples of API-related decisions include:

• What programming language will the APIs be implemented in? Many organizations give development teams freedom in choosing what language they use to solve the problem. After all, polyglot programming is one of the highly touted benefits of the API architectural style. However, there are practical limitations on an organization's ability to hire, train, maintain, and secure code across every language. While it may be a decision decentralized to teams, they may select from a "blessed" tech stack (a centralized decision).
• Whether an API must have an OpenAPI description, written to a certain quality, to appear in a centralized portal. In some places, that is table stakes for all registered APIs. In other areas, creating and maintaining an OpenAPI description is left up to the API developers' willingness.
• How the platform communicates performance metrics; are disruptions communicated by a centralized group? Or is there an expectation that each API development team maintains its communication with their integrations?
• Are consumer access requests (and the subsequent key generation) to an API done via centralized automation and self-service? Or are access requests routed to the API-producing team for a manual consideration of service impacts and support availability?

It is a mistake to think about decision-making as a binary thing – that either being entirely centralized or decentralized is always the "right" answer. The fact is that decision rights exist on a spectrum. And that slider may change for a host of good reasons: changing business objectives, marketplace pressures, or even team maturity. "Perfect", unchanging centralization or decentralization exists only in theory and is rarely observed in practice.

Another consideration is that the important decisions to one organization may be inconsequential to another. Start from an outcomes perspective and work backward to the decisions that will create the desired result.

Control Portfolio Configuration

Control mechanisms are the tools that platform owners use to implement and enforce rules that reward desirable behavior, discourage bad conduct, and spread standards among an API community.

Four broad categories of control mechanisms are as follows:

• Gatekeeping represents the degree to which the platform owner uses predefined objective acceptance criteria for judging what APIs and API developers are allowed into a platform's ecosystem. The platform owner sets these criteria for what and who is allowed in.
• Process control refers to the degree to which a platform owner rewards or penalizes API developers based on the degree to which they follow prescribed development methods, rules, and procedures that it believes will lead to outcomes desirable from a platform owner's perspective. Such desirable outcomes in platforms refer to APIs that will interoperate well with a platform, not whether they do well on the market. The platform owner prescribes these rules and procedures, who then evaluates the extent to which individual app developers followed them.
• Metrics refer to the degree to which the platform owner rewards or penalizes API developers based on the degree to which the outcomes of their work meet SLAs. As opposed to Gatekeeping, which is a control on the input, metrics are an output control because it evaluates the output of API developers' work. Other metrics may include the number of integrations, performance stability, or strategic partnership revenue.
• A Relational control mechanism refers to the degree to which the platform owner relies on norms and values that it shares with API developers to influence their behavior. This control mechanism thus depends on the platform owner to provide an overarching collective goal for the platform ecosystem; a sort of shared identity that defines the character of the platform ecosystem and rallies app developers around it by harmonizing their own goals with those of the platform. Such system-level goal-setting sets a trajectory to evolve the platform ecosystem and creates unity in effort without micromanaging API developers. This may be the most "soft skills" of the categories, but - when done correctly - it is also the most powerful.

In approaching governance on your platform, don't look at the above four categories and assume you must “pick one”. Several mechanisms should be used simultaneously in various amounts. Together, these represent a portfolio that encourages an ecosystem's desired outcomes.

A control mechanism is effective when the level of attempted control and realized control for that mechanism are not too far apart. This requires two things. First, the control mechanism should be accepted by API developers as being legitimate, fair, and reasonable. The power of a control mechanism requires the consent of the governed. Leadership is possible only when others choose to follow, so some consensus is always needed for any control mechanism to be realizable.

Second, its prerequisites must be satisfied in the relationship between the platform owner and individual API developers. Both conditions are likely to be met with some API developers and less with others.

That ultimately means that different collections of APIs may have the sliders set at different positions given their unique properties. Should an API that provides already available public information be required to adhere to the same expectations as a low-level implementation detail, like a microservice? Probably not. In these cases, providing a range of control portfolio configurations may be worthwhile based on the company needs (for example, these are the expectations for our private APIs, there are a different set of expectations for partner APIs, and so on).

Pricing and Subsidies

The third dimension of platform governance is platform pricing policies. Pricing policies aim to create incentives to encourage API developers to continue making investments. These investments net returns on their API efforts (however that is measured: signups, activity, or deals unlocked). Maintaining this balance ensures the vibrancy of the API ecosystem provided by the platform.

Issues of pricing and monetization also include what activities are subsidized by the platform owners. Any platform owner only has so much time, budget, and energy to expend on ongoing refinement. Subsidizing one audience – like building out SDKs to make the consumption of APIs easier means that enhancements aiding producers are in a backlog. Migrating all "legacy" APIs onto a platform without modification may be convenient for API producers, but now the API discovery consumer experience is negatively impacted.

A platform will survive only if it helps everyone in its ecosystem do better with it than without it. For a platform to thrive, owners must attract and retain API developers. They also need to balance the unique capabilities API developers value– from both sides.

Even internally, there may be questions around who pays for what – does the platform provide an internal chargeback mechanism for groups to recoup their bandwidth and compute fees? While having coverage for excess requests is nice, introducing a chargeback model introduces friction, especially when starting. Of course, attempting to add a chargeback model after things are running can be just as tricky – developers used to a “free ride” become very grouchy when they must unexpectedly find additional budget for an integration that was "done".

Pricing policies encompass five choices:

1. Whether pricing should be symmetric (make money on both sides) or asymmetric (make money on one side, give a break to the other) for the two sides of the platform.
2. If asymmetric, who is subsidized, and for how long? For example, an owner may provide API framework code to developers that easily integrates and onboards with the API platform. This is a subsidy for API producers, but how long does the platform owner support that codebase?
3. Pricing for access versus usage?
4. How will revenue be shared? If there is a chargeback mechanism, what is the platform's cut?
5. What API price point makes the most sense?

We're Only Scratching the Surface

I'm scratching the surface on how to categorize and compartmentalize the vast number of concerns a well-functioning API governance program might have. However, I'm already past the point where the newsletter provider threatens to cut me off.

I'd love to end this with some epic, pithy dump on those that complain about software governance, API or otherwise. However, if I apply even a modicum of empathy, I concede that those who complain the loudest about governance are mostly likely to have been previously abused by a lousy implementation. Those poorly considered, bruising, one-size fits all power-plays lead to some common misconceptions:

1. Software Governance is Only About Control: Some developers view any oversight as a Trojan Horse to impose one's will upon another. While governance may involve clarifying who decides what (as in the case of establishing design standards), its primary purpose is to ensure effort is aligned with business needs - be it consistency, quality, security, scalability, or something else. Good governance should enable effective decision-making, leading to more efficient (and aligned!) software delivery.
2. Software Governance Stifles Innovation: Another misconception is that software governance stifles innovation through imposed constraints. In reality, good guide rails can focus efforts on true differentiators rather than having teams expend time and energy "reinventing the wheel". While development teams have the best understanding of their domain, governance should be the group able to see both the forest and the trees.
3. Software Governance is a One-Size-Fits-All Approach: One way is simple. However, effective governance should be tailored to the organization's specific needs, goals, and culture. And just as those change, the governance should be flexible enough to change with it.

I'd be interested in knowning how much appetite there is for this kind of deep dive. Is this deconstruction and reformulation useful? Should I keep going? Let me know either in a comment or directly.

Milestones

• Matt McLarty and Mike Amundsen are launching a new show, The API Experience. Previously, the two hosted several seasons of the Mulesoft supported APIs Unplugged podcast. This new show seems unaffiliated with a corporate entity.
• Postman launched Postbot, an "AI assistant" that "will help you design better test cases". I'm a little unclear on why you'd need a LLM to generate test cases when you have a collection or OpenAPI structured data available. However, I look forward to trying it out.

Wrapping Up

I'll end with a thank you to my paid subscribers. I especially want to highlight Gary, our newest subscriber! Gary is one of the great individuals who has chipped in to ensure this newsletter is free of paywalls, advertising, or information selling. Because of Gary, and those like him, many folks can benefit from a little given each month. Thank you!

That's all for now. Till next time,

Matthew (@matthew and matthewreinbold.com)