What’s in an API Catalog?
This is the first in a series of what API Portfolios look like per industry. We open the series today by covering the basic components of an API Portfolio.
So… what’s under the hood?
We get this question a lot. We’re always excited to answer it because we’ve put a lot of time and experience into perfecting the core components that make up an API Portfolio. And we know they are the very keys to digital.
But before we get into the elements, let’s start with a visual.
What does an API Catalog look like?
For most companies, perhaps a folder full of hand-coded Swagger files, for the RESTful APIs, maybe XMLSpy for SOAP services… and as for the model and mappings — that’s a big part of it — that exists across a whole flock of documents and platforms. A list of requirements docs the PM loaded to Confluence, a handful of spreadsheets with multiple owners and versions (version control, anyone?), and even a few Word Docs. Progress is being tracked by Jira, and perhaps there’s even a printed out map of the wireframe, to show workflows with special instructions hand-scribbled from the project lead.
So the portfolio exists, but in pieces, across the whole tech stack. It’s not presentable, per say, but… it does the job.
There’s a better way.
A way to give a holistic view to both, Business and IT owners.
Figure 1. From this view, anyone, from Business or IT, can begin the self-serviceable Plan stage: innovating over inventory, grouping the building blocks with 3rd parties for a new API, specifying the flow and adding them to the Wishlist. From there your architect can use a customizable 5-step accelerator to guide team members through Design. The design-first API is already aligned to the information model and the business, so much of the Build is automated, and without much tweaking at all, it can be deployed to runtime within or directly from ignite.
This is just one of many powerful views within an ignite API Portfolio. There are many other ways to view coverage — top-down, API type, completion stage, APIs by associated terminology, and taxonomy/business domain view, to name a few.
Each one unlocks powerful insights that feed directly into business initiatives. But before we dip into the other portfolio views, let’s take a look at the what’s in an API portfolio: the components.
An API Catalog contains the following components:
- API Products
- Business Capability Building Blocks
- Sample Third-Party APIs
- API Resource Methods
- Domain-Based Information Model
- Baseline Classification Taxonomy
- Business Glossary
Figure 2. Your API Portfolio is what supports your 5 areas of digital transformation. We are seeing that most enterprise customers need to build out 400-2,000 Business Capability APIs across 10-20 business domains to reach a level of sheer operability and scale.
The core components of your API Portfolio underpin every stage of your API Product Management lifecycle, as you can see in the blue line above.
Our industry-based Foundation Packs help customers out by providing an industry-specific starting foundation for all of the gray boxes above, so that your teams can begin building MVPs from day one — and existing services can be imported at your leisure.
An API Product is a collection of Business Capability Building Blocks. These support your digital experiences by pointing to existing methods within your business capability model.
They can also be used to list a requirement for an API to be built, if that capability is not found in your portfolio. Because they are built within ignite, right next to the latest version of your business model, in an easily discoverable repository, there is no duplication of metadata or code.
Your services are therefore as light as they need to be, and you’re able to get reuse, and automation.
You’re also able to treat your digital products like physical products: they are well-documented, ownable, and searchable. Consistent, appealing, reliable, world-class.
Figure 3. If you click on an API Product, you open up a list of its constitution components and workflow.
Business Capability Building Blocks
Business Capability Building Blocks are the second layer of your API Portfolio (See Figure 1 above). They are essentially groupings of API Resource Methods that exist as abstracted business capabilities.
This is the middle layer of grouped miniservices everyone is trying to get to. When you look at the most well-structured companies out there — Amazon, Netflx, PayPal — they’re not just thanking their experience APIs for where they are today. They’re thanking the Business Capability APIs that opened up operabilty with a flatter architecture, opening data accessibility and lightening technical debt.
Many are looking at this layer like “Yeah, that would be cool and all but who has time to build that out?” The good news is, we just released industry-specific foundation packs to get companies started with resources, models, all of the portfolio components you see here.
Customers are able to import existing APIs and services, mappings, etc., combining their existing assets with the foundation packs as a good way to hit the ground running with 10x speed to market. (More on this later.)
Sample Third-Party APIs
ignite gives its customers the unique capability to manage third-party APIs if they were your own products. This means your teams are able to map them, attach your own metadata and policies, set KPIs, and track performance along your end-to-end story.
The value of having your own capabilities in the portfolio right next to third-party APIs is that you’re essentially looking at an ideation lab of opportunities. Many have an ever-flowing patent list — this is the chance to turn those patents directly into projects. Basically, an inventor’s dream. When building a complex API Product takes hours, rather than months, the world is your oyster.
API Resource Methods
We also call these cute little guys “miniservices”. (Oh boy, another API term…) At the most atomic level of your API building blocks, resource methods are designed and delivered from your Domain-Based Information Model (otherwise your foundation pack comes with industry-standardized resource methods that are packaged into your Business Capability Building Blocks and API Products), always consistent and always in the language of your business.
When you select a Business Capability Building Block or API Product from your guide view, a list of the Resource Method APIs that underpin each capability will appear below like so:
Domain-Based Information Model
Your Domain-Based Information Model uses terms created from the business and maps through to your API Products at the domain level, allowing for integration across regions and Lines of Business and supporting domain-driven microservice design, a best practice that allows your microservices to own their own data. This means you are able to factor functionality into your loosely coupled services, and changes can be made to the metadata of one API without affecting others.
The effect here: integrating multiple systems after an acquisition just got a lot simpler. When you’re able to map services and their associated terms to each other, not even language is a barrier.
Baseline Classification Taxonomy
To be used as an Industry Business Capability Model, with associations to your API Resource Methods, Business Capability Building Blocks, and API Products. The value here is increased visibility and searchability of your domains and their capabilities.
Integration across regions and Lines of Business is no trouble when your Business Glossary allows your teams to map associated terms to your APIs, Methods, and Information Model — allowing searchability for less technical users to determine if the model contains something related to the business term.
Again, one of the greatest challenges in this digital age is bringing Business and IT on the same page. Traditionally, there wasn’t much need — but now
A Few More API Catalog Views
Below are just a handful of the many portfolio views your rich data management will unlock.
API Portfolio Taxonomy View
For more information on our Foundation Packs, download the ignite Foundation Pack PDF here.