How to Achieve API Governance
APIs, which allow programs and applications to communicate with each other, allow for flexibility and team autonomy — but that pendulum needs to swing back. By the end of this year, 90% of new digital services will be built as composite applications using public and internal API-delivered services, according to projections by IDC, a global analyst firm.
More and more organizations understand that, with all these APIs popping up everywhere, their API strategy demands a unified view, with common design patterns, central discoverability, and generally taking an approach that will make APIs more easily consumed by more users. This demands API governance.
Why Are APIs Important?
At their very core, APIs are delivery mechanism “interfaces” that provide a way to unlock and deliver value to consumers. Then, as everything API strategy has to connect back to business, that consumer value should translate to direct profit, increased customer retention or other benefits.
As long as your API can handle the load, you can easily scale consumers. Let’s say you have a weather app that has released a weather open API. Here, the weather API can be extended to support smart devices for smart homes, smart cars, etc.
This ingenuity also allows for innovation, where your possibilities become more diverse. You can take your API service to areas you had not initially thought about, like monetizing through sporting and event planning, or allowing universities to build climate change solutions atop your API.
As your API becomes more popular, some scenarios come up that perhaps you had not predicted, which means you must change or improve the API a little bit. You must update or upgrade it to include additional features, ones demanded or expected of the population that is consuming your API.
Centralized API management — especially with a developer portal, that allows you to understand more about your developer experience — can give you the edge you need in responding to user behavior.
How Can We Make APIs More Valuable?
The value of an API is in its consumption, and the consumption extends over various API releases. With each release, the API is tweaked, thus ending up with the enhanced potential to attract more consumers.
With API lifecycle management, you improve your product, thus getting more users over time without harming user experience — hence, driving more value.
The overall value of an API is the value that you create over the existence of all its different versions. Your goal as an API architect is to optimize this value by improving your API with an iterative approach over time, where you prepare the API to attract a few more consumers.
4 Challenges Facing API Product Management
There are some well-known challenges for API products that you must consider when you manage the lifecycle of your organization’s APIs:
- Adoption: API design familiarity, including consistent endpoints and error codes, allows for easier adoption, based on technologies familiar to most developers.
- Velocity: Improving an API’s performance increases its value by keeping up with new features requested by consumers of your API.
- Breaking changes: You want to keep up with the velocity without breaking your APIs, so that existing consumers don’t have to adapt to the changes unless they want to.
- Productization: APIs must be useful, easy-to-find, usable and predictable.
Scaling Your Developer Experience
To scale your developer (i.e., user) experience, you need to look at the bigger picture “the entire API landscape” and not just a single API.
Not only will you have different consumers accessing one API, but they will mix and match different APIs to build their own experiences. These experiences will be built by the designers on the consumer side; they will combine the APIs in a way that makes sense for their users.
The main question to ask here is “How do you plan for such a scenario?” This is where API governance and scaling come into play, because now we are not only looking at what is the best way to manage that one API but we are looking at the best way to manage the entire API landscape, so that we can scale those experiences much better.
The more we design and optimize the experience for the entire API landscape, the more we can create a better UX that translates to more value generated.
One crucial thing to keep in mind is that, in the end, even though we are striving to get the best UX, that’s not all that matters. Somebody should also discover the APIs, use the APIs, write applications that use the APIs and fix the applications when the APIs have breaking changes. All of these depend very much on how the APIs are managed, making the developer experience — also called DX, DevEx or developer enablement — a limiting factor.
This is important because — if we look back at the fundamentals — APIs are languages, a way for computers to talk to each other, and this communication is driven between developers.
Once developers have built an API-consuming application and a breaking change occurs in the API, they must go back to the application’s code and apply a fix or change. The point to keep in mind here is that computers aren’t good at dealing with change, so you should consider and implement change management that works well for computers.
Regarding large-scale API governance, it is important to consider how to allow your landscape to grow but also manage it, so that the growth creates as little disruption as possible and operations continue to work smoothly as you can make them.
Cultivating API Landscapes
API governance is the guardrails you put in place to assure quality, security, compliance and more, usually via a platform-based approach to API lifecycle management.
To achieve a better scaling experience with good API governance, you must think about the API landscape you are trying to build. How can you get the most value out of it?
This brings in yet another challenge, where you have a complex optimization function across all APIs, across their versioning behaviors, and taking into account the desire of API owners to improve their APIs. Managing all of these is not a trivial task, but if you put your mind — and your tooling — to it, you can get it done.
5 Challenges for API Landscapes
- Innovation: Allow new patterns and practices to evolve, and design them in a way that people can build new interesting things without being too restricted.
- Coordination: Prevent bottlenecks that can be created using centralized processes, but maintain a centralized view and access control.
- Productization: Manage all APIs by balancing autonomy and coordination. You must know your landscape, what it looks like, what’s in it, and what you want to optimize for. You also need a view into your users, often via a developer portal.
- Stability: Makes it possible for people to build enhancement in it with some level of reliability required so that functionality doesn’t break too often. This can be achieved by introducing automation tooling in your API pipeline management. Utilize open source tools such oasdiff, which can be implemented in a CI/CD of your choice, to detect configuration drift or breaking changes.
- Consistency: Balance local versus global optimization. If all APIs follow similar patterns and practices, it will be much easier to understand them. If every single API is designed in a completely different way, it’s hard to use as many, and much harder to understand how they work and what they do.
3 Steps for Achieving API Governance
What follows are milestones to help you minimize the challenges we’ve discussed in making your API landscape productive.
1. Observe with Insights
Combine decentralization with the ability to gain insights. This means that if you have an API, it is possible to learn about it where you can query for information (such as the technical description of interface mechanics, e.g. OpenAPI, documentation), metadata for API lifecycle management (e.g. schema.org), versioning history, etc.
In a landscape where there’s standardization and the API is making a statement about itself, it’s much easier to manage the landscape, because you can just go to the individual APIs and learn more about them.
2. Harmonize with Interfaces
Provide clear guidelines — but set up guardrails, not gates. From there, aim for the minimum number of constraints for your API landscape, ones that ensure flexibility and innovation, without putting quality, compliance, or, of course, security at risk.
It helps when the interfaces of the APIs have certain consistency — commonly used endpoints, clear error codes, documentation — because the consumers will easily understand your APIs. If this is done in a way that’s clear to follow, both API providers and API consumers can benefit from them.
As a result, you get coherence of interfaces to those API capabilities that are easier to use which reciprocates for the API consumers who can better use the capabilities available in the landscape.
3. Support Your API Builders
How can you nudge the engineers that build APIs into building them the way you’d like them to be? Tooling, like an API management platform, can help put in place those guardrails. It also enables reusability, so you can create templates from existing APIs that illustrate best practices or common use cases, cutting building time for other engineers across your organization.
API Guidelines as Shared Practices
Building out guidelines for your developers and infrastructure support teams helps send them in the right direction. Those guidelines provide a methodology to solve API problems consistently, which helps the API landscape and tooling that can:
- Validate APIs to increase API product quality.
- Simplify implementation and reduce API time-to-market.
- Help with consumption and increase realized API value.
These guidelines help shape the teams that are building these APIs, thus allowing you to influence the API landscape and achieve effective API governance.
Not sure how to get started in setting API guidelines? Here’s a list of openly available guidelines by some large organizations.
API Governance Is Landscape Lifecycle Management
API lifecycle management helps with improving an API’s value, while API governance helps with improving the value of the entire API landscape.
The best possible way to achieve good governance is by understanding what you are trying to achieve with your APIs. Then you can create the best user experience, which you can deliver to the maximum number of people who can extract more value from the API landscape.
It’s also crucial to keep a close eye on developer experience, ensuring the APIs are easy to find, understand and use, and are stable — so that when your ecosystem starts scaling up, you can henceforth make it more productive.
Remember that good API DX coupled with good API landscape DX contributes toward having an overall improved user experience. And this all comes down to putting the proper API governance in place from the start.
