At small scales, it’s easy to make sense of the software your team produces. You may have a handful of Git repos. You have a single project management tool to track bugs and features. For large enterprises, things change. You need to look across many different business units, thousands of engineers, and often hundreds or more APIs driving their software.
We talk to large companies with many APIs. Their business counts upon those services to enable their internal and partner engineers. Yet, when they attempt to quantify their API program, it’s typically in a range: for example, somewhere between 5,000 and 10,000 services. Both are huge numbers, but more shocking is the distance between the estimates.
It may be unrealistic to determine at any moment the exact number of APIs you’re running. All enterprises serious about understanding the lifecycle of their software should look to improve their estimates. More important than the actual number are the insights you can glean when you’re able to analyze your API program.
Enterprise API Governance Needs Visibility
Every API your company creates goes through a lifecycle, regardless of whether you have a defined process. It’s easy to think only of the design and build phase because these are often tied to important milestones. An API is likely to spend much more time in the later phases of the API lifecycle. Yet, this is the time when your API becomes less visible, especially to those not involved in the maintenance and support.
Your API governance procedures allow you to set quality and style guidelines for new APIs. Typically, this also happens at the start of a new API project, as a way to ensure consistency. You don’t want teams to recreate how endpoints are named or pagination is performed. Unless there’s good reason, each API team should select from a very small menu of options in coherence with your program standards.
It might be desirable to see how closely your whole API program follows your guidelines. However, in many companies, old APIs are viewed as technical debt. Left unpaid, a growing unknown number of non-compliant APIs can cause enterprise anxiety.
New APIs also benefit from the knowledge locked in your existing APIs. Without visibility into what services are available and the pieces within them, your teams can’t build upon the good work that’s come before.
API Designers and Consumers are Flying Blind
Most API discovery solutions are focused on finding services. That experience is rarely fantastic when APIs number in the 100s or 1000s. And it’s even worse for API designers, those who work at the very early stage of an API lifecycle.
Each new API should not have to start from scratch. Most enterprises have at least lightweight governance in place. These guidelines are typically applied after design, so they’re only a little help during the design phase. Yet, within the company’s many APIs are likely the building blocks for the majority of any new API—existing response models, error formats, and examples.
In a financial services company, for example, you already have common schemas for resources like customers, accounts, and payments. These concepts are so central to your business, that many APIs will use them. Yet, the manual process required to discover those design assets leads to teams recreating much of their API anew, instead of leveraging the knowledge already in their organization.
If you can’t answer how many APIs you’re running, you also don’t know how many return a customer object. Nor do you know the number of inconsistent customer objects in use across your organization.
Answer API Questions Big and Small
“How many APIs are we running in production?” is a big question. It requires that you first have a way to corral your various services, ideally described in a format like OpenAPI. You also need to know the state of each API in the lifecycle, as many teams are frequently making changes. To answer the big questions, it helps to be able to answer the small questions.
The Stoplight team has been working to help our customers visualize their API programs. Many companies already have the pieces, but they haven’t collected them in one place. OpenAPI definitions, JSON schemas, and other API descriptions all tell a story of how your APIs are built and where they’re interrelated.
Answering small questions, like “How many customer models do we have?” is followed by bigger questions:
- How many APIs refer to each model?
- How different are each of the objects?
- What will happen if we change one of the models?
When API dependencies—and their underlying design assets—are discoverable, it can transform how you build and operate APIs. You could have a whole new view of the software that runs your business.
