With the number and types of APIs growing exponentially in enterprises, how do you effectively organize them at scale? Proper API organization helps enable discovery, reuse, reporting, and evolution to a composable enterprise. Use the 4 tactics in this article to properly organize all your APIs across all environments and lifecycle states.
Jump to:
- Why is organizing APIs so important?
- Of course, it’s more than only APIs – so organizing at scale is hard
- Tactic 1: get everything in one place
- Tactic 2: group APIs into abstracted Designs
- Tactic 3: classify APIs
- Tactic 4: normalize APIs and standardize the process
- Benefits of good organization: API discovery, reuse, reporting, composability
Why is organizing APIs so important?
The growth in popularity of APIs to support all things digital means many organizations now have a lot of them. We’re talking thousands – we regularly see our mature enterprise customers having 6000+ – and that number is growing.
With lots of APIs like this, and the ever changing nature of a digital enterprise, it goes without saying that you don’t want one big “junk drawer” of APIs (or even worse, lots of little ones across platforms and repositories!).
After all, APIs are only really valuable if your consumers can find and use them to build the differentiated products and services customers want.
A lack of proper API organization means:
- You have more API duplication. If you can’t find existing APIs to reuse in part or as a whole, APIs are likely to be regularly duplicated. This increases development time and costs, and puts pressure on already overstretched developers.
- It’s hard to engage more roles in your API ecosystem. An extended audience for your APIs is key to reaping the full potentials of the API First approach. You want everyone on the playing field (including business technologists) to unlock collaborative innovation.
- It’s near impossible to understand (and report on) how APIs are supporting business capability coverage. What’s your coverage and gaps? What’s “good” and in compliance? How much is reusable?
If these issues aren’t addressed, it’s fundamentally difficult to become a composable enterprise. That’s where capabilities are modularized and can constantly be reused, repurposed, and repackaged.
Of course, it’s more than only APIs – so organizing at scale is hard
While we’ll continue to use API as an umbrella term in this post, enterprises are working with much more than APIs. In reality you likely have:
- Different interface types e.g. SOAP web services, REST APIs, Async APIs. Often you might even have different interface types for the same capability. For example, a legacy SOAP that’s due to be deprecated, and a newer REST that not all your consumers have migrated to yet.
- Different Design and Specification types e.g. public, partner, integration, enterprise business services and internal APIs.
- Many API versions at different stages of the development lifecycle.
- Different platforms and implementations e.g. some APIs sitting on many gateways, while some are just held as code “somewhere” in the enterprise.
How do you capture and organize all this at scale? These 4 tactics will help…
Tactics for API organization at scale
1. Get everything in one place
First thing’s first, API sprawl is a total blocker to effective API discovery, reuse, and reporting. API sprawl = APIs scattered all over the enterprise, with no source of truth for what’s out there.
And runtime API catalogs (the ones that tend to come with traditional API management platforms) don’t help with this.
They’re only capturing APIs on that particular gateway. Nor are they capturing APIs that are currently being designed and developed; only the ones that are live and running.
What if there’s a perfect API candidate for an application that’s weeks away from being deployed, but the app developer can’t find it? That’s a missed reuse opportunity, and an added development cost.
The first step to proper API organization is therefore to create a single pane of glass for everything that’s present in the enterprise – both in production and in-flight. ignite’s Holistic Catalog is a great option for this because you can import and harvest existing APIs from all environments. And, as it’s tied to the full API lifecycle, new APIs are designed in ignite too.
2. Group APIs into overarching Designs (with interface types and versions nested)
When we talk about composability, a key goal is to be able to reliably expose your capabilities as the interface your consumer needs.
So, it’s important to be able to organize your APIs in an implementation-agnostic way, i.e. organize as abstracted capabilities. ignite customers are using abstracted Designs to do this.
SOAP, REST, and Async APIs, along with all their versions, are organized underneath this abstracted Design. That way, you’re capturing all the variations of the same function under one roof.
This approach is also helpful for enabling business roles (e.g. product owners and business technologists) to find, use, and work with your APIs. This is because the Design is easy to understand without having code expertise like developers do.
3. Classify APIs and align to your business capability model
In a previous post, we delved into why you should be aligning your API program to your business capabilities. Viewing APIs as an interface into business capabilities, not backend systems, helps realize the promises of API First, and results in happy customers!
That means taxonomy classification is important – what taxonomy node(s) from the capability model is each API supporting?
Track that for all API types and versions across the ecosystem, and you’ll start building an accurate picture of your coverage. You’ll be able to identify any gaps in capability coverage too, and prioritize where to direct resource to build new. (A quick note that ignite enables this classification in an easy-to-use user interface (UI) in the platform. Classification can also be set as a governance “must” rule across the lifecycle).
4. Normalize and standardize your API program and process
For successful API organization at scale, you want to manage everything in a standardized way. From a standardized repository of normalized assets, to standardized processes and workflows.
This helps bring the benefits of organized APIs to the forefront. You create transparency, consistency, and predictability across the integration ecosystem. API discovery and reuse are only really valuable when your consumers can reliably integrate with the APIs they find. And API reporting and composability are only unlocked when you have consistency.
To ensure this we recommend:
- Validating all APIs against technical standards (e.g. OpenAPI validation). You only want valid code in your ecosystem that conforms to the particular protocol or style.
- Ensuring your enterprise’s security and common policies, governance rules, and standards are applied to your APIs. To ensure APIs are reliable, compliant, and consistent. This should be done in a flexible way, so while not all API design types might need the same level of governance applied, there’s standardization between the way the rules are applied.
- Manage, extend and update, approve, and deploy APIs in a standard way. Ideally from one central platform (and even better if that platform combines the catalog with the lifecycle, like ignite does).
Benefits of organizing your APIs at scale
TL;DR, effectively organizing your APIs at scale dramatically improves:
API Discovery
It’s easy to find what APIs are available (even those across lifecycle stages). It’s also easy to understand what the API does and what business capability it’s exposing – and both business and IT roles can do that. Plus, you have a reliable source of truth for your API discovery, and can easily find all API versions and interface types under one central Design.
API Reuse (in part or as a whole)
If APIs are easy to find and consume, you can drive reuse and reduce API duplication. This speeds up development and reduces cost. Plus, because your assets are standardized and predictable, consumers know what they’re getting when they’re reusing existing APIs in their applications. They can also reuse in part or as a whole.
API Reporting
Because APIs are properly organized in one location, you get an accurate view of coverage and gaps of your portfolio at the business capability level. Plus how standardized, consistent, and compliant all your APIs are as you’re going through this process. This helps with proper API and project prioritization and estimation, and even enables you to assess your overall API maturity.
Evolution to the Composable Enterprise
By utilizing the tactics we’ve discussed, you’re organizing your APIs as digital building blocks instead of project by-products. Capabilities can be reliably exposed as whatever interface is needed, both now and in the future. If APIs are meant to enable the composable enterprise model, then proper API organization in this way is a secret sauce to make this a reality.
So, with these tactics now in your toolkit – happy organizing!
If you’d like to see how the ignite Platform enables API organization at scale for effective discovery, reuse, and reporting, book a demo today.
