It’s the 21st century, and APIs are only becoming more prevalent. Not only are they springing up in a growing number of organizations, but they’re also being built in numbers: dozens, hundreds, and thousands.

So how can you build large-scale API ecosystems with more confidence, in a truly systematic way? Erik Wilde of Good API thinks he has the answer with API Landscaping.

This article is based on Erik’s session from the 2018 Nordic APIs Platform Summit in Stockholm, Sweden, and walks you through the concept of API Landscaping start to finish — what is it, why you should care, and how you can implement it.

The Problem

Every organization has the vision of digital transformation: embracing modern, computer-based technology in their everyday business process, consumer-facing or otherwise. It’s a pervasive vision, and not a very original one.

Erik thinks you can write a generic digital transformation vision statement that holds for pretty much every large organization. Here’s what his looks like:

“Our digital transformation initiative will turn us into the leader of the industry by allowing us to interact with our customers more easily, and more frequently. By increasing the number of customer touchpoints and using the resulting feedback to quickly and relentlessly adapt and improve our offerings, we will be able to outperform our competition and turn into the market leader within the next three years.”

Erik jokes about creating a template for your organization’s digital transformation vision statement, but in any case, there’s a serious issue at play here.

Every large organization says they’re undergoing a digital transformation — the vision is clear. But the path to realizing that vision isn’t.

The Two Pillars of Digital Transformation

Erik believes that you can split digital transformation into two categories: API strategy and scaling solutions. The API strategy is essential — it’s what allows you to build complex, digital ecosystems — but the scaling of these APIs is equally crucial, and it’s how you turn a vision for large-scale digital transformation into a reality.

Erik believes that, at any given time, you should be able to assess your digital transformation progress, and, if necessary, correct your course. For this, you’ll need a plan, with clear reasoning, resource allocation, and development metrics, among many other things. At present, most organizations don’t have that plan at all.

The API Archaeology

If you want to build superb vast API ecosystems, you need to understand the science that Erik calls API Archaeology.

API archaeology is looking at an organization and assessing what stage they are in of the API strategy lifecycle. According to Erik, there are three stages:

1. Proto-API: The organization is new to the world of APIs. In a sense, they already have API-like systems — although we might not call them that.
2. API Craft: The organization has begun implementing APIs on a small scale. And they work!
3. API Landscaping: The organization has a growing number of APIs, and it’s time to start thinking seriously about how the API strategy will scale.

Autonomy for API Developers

In most organizations with multiple teams working on APIs, there’s a typical structure. An organization-wide API strategy team provides a supporting infrastructure for API development. This means they share knowledge, standards, and tooling.

Then, underneath the organization-wide strategy team are individual API product teams. They often have autonomy over their development process, but they’re encouraged to (and do) draw from the organization’s supporting infrastructure, using the shared knowledge, standards, and tools to avoid reinventing the wheel.

Overall, this is hugely effective. The API product team can focus on solving their problem, taking whatever approach they need, but they can draw value from the organization’s API strategy team in an economy-of-scale fashion. Of course, executing this approach well is about finding the right balance between autonomy and support.

Often, organizations publish guidelines for how APIs should be built. Erik suggests you structure these guidelines with four core points:

• Why does the guideline exist? (What problem does it solve?)
• What design addresses the problem?
• How do you implement that design?
• How do you test you’ve done everything correctly?

But the real principles of API landscaping are in how you maintain and evolve those guidelines!

API Landscaping in 8 Principles

As far as Erik is concerned, API landscaping can be divided up into eight different principles or aspects. We’ll go through each of them individually and see exactly what he means.

Variety

Don’t build a monoculture for how your teams build their APIs. Allow them to come up with new solutions and pivot approaches as necessary.

Vocabulary

APIs are a language. Reuse vocabulary between API products wherever possible, like in error messages. Where are a standard is possible, use one! We’re a big believer that building on open standards will increase IT longevity.

Volume

Having lots of APIs is good. Don’t let a fear of having too many APIs limit you. Some APIs will die while others will flourish — allow the natural selection of APIs to take place! Many are finding a high volume necessary with the prevalence of many microservices.

Velocity

Build an API ecosystem where individual cogs can change. Allow that change to be loose. Changes in how consumers use APIs should be invisible to producers and vice versa.

Vulnerability

Every API is a potential attack vector. Encourage teams to foster a culture of security, take responsibility for security, and build a robust, organization-wide strategy for securing APIs.

Visibility

Allow your APIs to be discovered. There’s a spectrum of discoverability for each API, depending on whether it’s public, partner-facing, or private. In any case, allow those who need to find your APIs to do so.

Versioning

APIs should evolve. Help your teams to do it responsibly by employing someversioning strategy.

Volatility

Products will appear, change, and disappear. Build your API ecosystem in a way that the majority of the machine can still work even if one cog is broken.

Evolving Guidelines

Together, these principles for API landscaping give you a good idea of how you can evolve your organization’s API design guidelines. In turn, that allows you to readjust your API strategy across your organization, ensuring a consistent and predictable implementation that will take the headache out of scaling APIs.

If you want to ensure you evolve your guidelines as smoothly as possible, Erik has suggestions for that too. He likes “build the best API you can at any given time” as a rule of thumb, and looks to continuous architecting as a guiding methodology. One interesting principle is that you should build timeless interfaces — so products across your organization look and feel the same over time — and focus on creating flexibility through implementation.

Final Thoughts

To wrap things up, Erik draws attention to the fact that ecosystems will always win over systems. The curious dynamic is that systems are more comfortable to build but harder to change, while ecosystems are harder to build but easier to change. It’s this flexibility that makes ecosystems so good for your modern-day digital transformation strategy, but you should employ these API Landscaping principles if you want your APIs to scale the way they should!