APIs are everywhere within your organization. Many may be internal, but we’re willing to bet there are many third-party web services and APIs that your business depends on too. Keeping track of them all, and ensuring that your team chooses the best APIs for their needs can be a challenge. In some cases, your organization may be using an API they don’t even know about. The solution to this “web of APIs” is to apply the concept of API governance to your API dependencies.
What is API Governance?
Before we go into applying the concept to third-party APIs, we should look at what API governance is.
API governance is a set of policies and procedures that act as guidelines for how your organization uses APIs. Governance is all about security and reliability. It can take many shapes, but it helps with things like:
- Establishing criteria for choosing APIs.
- Defining any shared standards, like security, that APIs will share.
- Aids in the discovery of existing APIs in the organization.
- Laying out plans for usage, versioning, etc.
This process makes a lot of sense when a good part of your stack is dedicated to providing APIs, but what about the external APIs that your organization consumes? Can you apply a similar approach to the APIs you depend on, even if you don’t have control over them?
Applying the idea of governance to third-party APIs
As your organization grows, there’s a high likelihood that every API consumed won’t be known. Development teams working on different products and services may have some overlap, but what are the chances of two teams signing up for the same API? What about choosing two differing APIs that serve the same purpose?
For third party APIs, the governance process can lead to two key artifacts: an API catalog and a set of guidelines for choosing APIs. Let’s look at some API governance best practices, but applied to third-party API dependencies.
When we onboard new customers to Bearer, some often discover that their organization is using APIs they didn’t know about. This isn’t unique to giant organizations either. Even small teams can run into this problem. An API catalog can be a valuable way to centralize details about all the services and APIs that your organization uses. The format this catalog takes can change with the needs of your organization, but the benefits can directly affect your development teams as well as your business strategy. Let’s look at a few benefits, and things you may want to include in your own API catalog.
By collecting details about each API, your team can create a centralized location for the whole organization. This allows teams to discover which SaaS providers you already have a relationship with, and which services are currently available.
This is also a great way to avoid duplication across teams, and avoids the selection of similar APIs that serve the same purpose.
Service-level Agreements (SLA) are a contract between your organization and the API provider. It can often be hard to keep track of expectations at a high level. A central catalog of APIs offers a place for all SLA details to be stored.
You can take this a step further by incorporating monitoring to ensure that services are meeting their requirements, and even tie this directly into the catalog for at-a-glance oversight.
Centralized Test Coverage
While it may not be feasible or even possible to incorporate testing directly into an API catalog, it can be an excellent place to store coverage statistics. How are, or perhaps in the dark, are you about the last time tests were run on a particular API endpoint? Is it possible there is a rarely used API in your stack that has been down for a while, unbeknownst to your team? Bring the results into your API catalog.
Are you paying for service that you no longer use? By tracking API usage across an entire organization, you can examine areas such as:
- Which teams are currently using an API?
- Is the organization on the most cost-effective plan?
- Are there multiple, similar APIs in use when a single one could suffice?
- On pay-as-you-go plans where you pay for each call, are you often over budget?
The centralized test coverage portion covers part of this benefit, but your API catalog can act as a central knowledge base for every API in your organization. This can include things like:
- Internal documentation related to an API (like a Postman collection).
- Links to status pages, official documentation, and examples.
- Locations of credentials.
- Points of contact for API consumers in each department.
You can use an existing solution to create the catalog, though the space is mostly filled with API management platforms designed around providing internal APIs to your teams. Alternately, you can build your own solution or add the functionality to a tool you already use. This catalog is essentially a content management system (CMS) that stores the necessary information about each API as mentioned earlier.
Make the process of registering APIs to the catalog easy—or even automatic—for developers, as it will increase the adoption of the centralized hub.
Defining API Selection Guidelines
How does your organization select which APIs to implement? Does each team—or developer—make decisions on their own? Is there an approval process? Are there restrictions on what kinds of APIs makes it into production? What about SLA requirements?
These questions, and others like them, are the foundation for defining a set of API selection guidelines. In many cases, you will be starting from a point of existing API dependencies. This is a good time to assess the landscape. Poll your teams, collect the data, and organize it. While existing APIs can be excluded from a selection policy, it is good to at least compare them to the guidelines you set. Start by defining the criteria that new APIs will need to meet. These criteria can include:
- A minimum set of SLA requirements (uptime guarantees, time to response, etc.).
- Deprecation timelines and versioning details.
- Cost vs. Value: Are there alternatives at lower costs? Is it worth it to build instead of buy?
- Cross-team impact: Will an API be useful to more than one part of the organization.
- Support availability: Does the price come with reliable support, both for the development with and management of the API?
- Stack compatibility: What stacks have SDKs, and what would it take to continue using the API if your stack changes?
- Ease of use and depth of documentation.
- Data policy: Whether handling GDPR compliance or HIPPA laws, an API’s data policy has a direct impact on your own data management.
Enforcing governance and adding value to your organization
With a catalog set up, and guidelines in place, enforcement keeps the process going. It’s important to establish a set of processes that doesn’t limit your teams ability to experiment and work efficiently, but also protects your organization from the shadow APIs that suddenly appear in your stack. Make sure the approval cycle is low-friction and the monitoring of new and existing APIs makes it easy to track usage.
Governance is a way to bring structure to your organization’s dependence on APIs, but it shouldn’t be yet another piece of technical debt. The good news is you don’t need to dive all-in right away. Simply starting to monitor API usage and performance across the organization as a whole is an excellent first step. At Bearer, part of our offering helps with this by automatically monitoring API calls and organizing them in a central dashboard. This is one way to quickly view which APIs you are using effectively and monitor them from a performance, SLA, and anomaly standpoint. Explore ways to tie governance into your existing processes. The catalog can even live in your team’s internal knowledge base.
Take the first step toward adding more observability and oversight to the APIs that your organization uses. Set up a policy and implement the appropriate tooling to control and enforce the policy. This will help build a culture around scrutinizing and monitoring API dependencies and improve the overall resilience of your applications.