One of the key tasks of supporting a vital API program for your company is dealing with change over time. In previous articles, I’ve talked about the importance of managing the entire API lifecycle and how to recognize important milestones in the life of an API. These milestones often signal that a change in the way the API is treated, measured, and managed needs to change.
It’s important to note that each API has its own lifecycle — that not all of your APIs are at the same stage at the same time. Some APIs are in early design and trial stages, others have been realizing value for your company for a while, and a few others need to be placed in maintenance mode to reduce needless expense and effort. APIs are not a monolithic group.
And that leads to another key concept that all API design and governance systems need to deal with: API landscapes.
Your API landscape
Your API landscape is the sum total of all the existing services in your company and all the APIs that connect them together. You can think of your company’s API landscape as the API portfolio covered by Matt McLarty in his “Four Ps of API Governance.” Whether that API was custom built by your team, purchased as an online software-as-a-service, or simply a collection of gateway policies, your landscape includes all the bits and pieces that allow connections in your organization. The landscape requires management too.
So, just as your APIs are not all at the same stage in the API lifecycle, not all the components of your API landscape are at the same level either. You may have several “legacy” APIs, some off-the-shelf platform APIs, and some remote services you use regularly. These all make up your landscape. And each pocket of technology, each set of bespoke APIs, each collection of policies and scripts need to be included in your governance and management plans.
But with all this variety, how can you consistently plan, measure, and manage your API landscape? What is needed is a set of principles or guidelines that stretch across technology and design details and get to the heart of good interface management.
What you need to keep track of are the eight challenges of API landscapes.
Dealing with the eight challenges
My colleague Erik Wilde has been talking about managing API landscapes for several years and captured much of his research and recommendations in the book O’Reilly “Continuous API Management” (2018). In that book, the notion of a long-term approach to API management is discussed and a set of eight challenges (all words starting with the letter “V”) are introduced. “These eight Vs are like the controls or dials for your API management system,” the book points out. “You’ll need to observe and tune them to get the best results.”
So what are those eight “dials” for managing your API landscape? Here’s the list with a quick comment on each.
Variety
At the start of your program, you’ll want to limit the variety of API styles and formats. Keeping the design and implementation details of your first APIs homogeneous will allow teams to focus on functionality and deployment without getting wrapped up in philosophical discussions about the “best” way to update a record or whether one library or another is the proper way to implement an API.
However, as your program matures and its reach grows to encompass more teams and more customers, you will encounter more unique use cases, different customer needs, and — as time goes on — updated technologies and changing preferences. It will be important to not just allow, but to introduce variety into your API landscape.
When you find your governance and design guidance running into consistent opposition, that’s usually a sign that you need to update your guidelines to acknowledge important new varieties in your API landscape.
Vocabulary
Establishing an approved interface vocabulary of data property names (givenName) and action identifiers (approveLoan) is the most effective way to improve interoperability across teams. Adopting and maintaining a rich external API vocabulary that maps to a service’s internal data and object models allows teams to modify internal details of a service without breaking the external API used by consumers.
Programs that carefully manage their API vocabularies have the best chance of building and maintaining interoperable systems.
Volume
Early in the life of your API program the number of running services and published APIs is relatively small and can be easily managed from a central location. However, as the volume of your services and APIs increases, single-source review and approval will not scale. As your service and API program grows you’ll need to “farm out” responsibility for reviewing, approving, and managing your APIs to a wider group of skilled software architects and engineers.
The increasing volume of services and interfaces means you need to change your governance pattern from a centralized model to one that is more distributed.
Velocity
Similar to the volume challenge, as you add more APIs and more teams, you’ll need to address the time-to-market challenge. Sharing best practices and automating review and approval processes can cut down the time it takes to bring an API from idea to install. Growing programs will experience pressure to speed up the process of creating APIs. That means adding more automation and safety checks to your API implementation process.
Increasing the speed to deployment should never reduce the safety of your API landscape.
Vulnerability
As your API landscape becomes more varied and powerful, your organization is likely to encounter more risk, too. Each API you add is another API that might crash or suffer an outage. In a monolith, the risk is centralized and limited to problems related to your code and hosting hardware. But APIs introduce an added dependence on the network that carries API requests and responses. More APIs means more network which means more opportunities for outages.
As you add calls to other APIs, make sure you also implement “fallback” scenarios that allow you to keep operating even when one or more of the APIs you depend upon are not functioning properly.
Visibility
A big challenge for growing API programs is maintaining the proper level of visibility across the ecosystem. It is important to keep track of how long it takes to implement services (“idea to install” again). It is also important to keep track of what services are currently available and how to connect to them when needed. Finally, it is vital to track the performance and success of each API in production to determine when APIs need to be updated and when they need to be retired.
In the beginning, when you have few APIs in production, you can keep track of this information with hand-rolled spreadsheets, user-supplied change tickets, and API gateway logs. However, as your program grows, you’ll need to introduce automation into the process of monitoring implementation details, deployment status, and service performance.
When you find your service history and tracking information is falling out of date, your reaction should be to introduce automation and real-time reporting to your API landscape.
Versioning
The more APIs you have in production, the more changes you’ll need to manage in that ecosystem. Updating APIs is an important part of maintaining a healthy API landscape and, as your platform grows, you’ll find that there will always be some API in some state of “update.” Companies that are good at managing their API landscape make API versioning safe and commonplace.
The preferred approach for updating APIs is to make all changes non-breaking and backward-compatible with existing versions of the API. When that’s not possible, you need to implement side-by-side deployment where multiple versions of the API can safely co-exist in production.
Either way, as your system grows you’ll need to manage an increasing number of changes to existing APIs.
Volatility
Finally, as your API landscape grows, so will your security footprint. Using more APIs means more network traffic which introduces more opportunities for network-related attacks. Early on, your APIs may only operate within your company network but, over time, you may add APIs for partners or even end-users. These all add risk to your ecosystem.
Also, as your company leans more on APIs to get work done (both your own and those of other third-parties) you become more vulnerable to problems experienced by other APIs upon which your company depends. Therefore you should treat any third-party API you consume as a potential threat either through simple network failures or as an attack vector.
A growing API landscape requires added attention to security too.
Getting the best results
Just as managing a single API lifecycle means paying attention to several things at the same time and focusing on different challenges along the way, managing hundreds or thousands of APIs has its own set of challenges. Erik Wilde’s “Eight Vs of managing your API Landscape” gives you a set of system-level behaviors to watch for as your API platform grows and you add more teams to your ecosystem. Keeping an eye on these eight aspects of your platform will give you the ability to recognize typical challenges and give you a head start on getting the best results you can out of your API landscape.
To learn more about the product management practices of APIs, check out the “API-as-a-Product Workshop,” one of MuleSoft’s API Program Workshops.
