Many organisations I partner with in consulting engagements have a large inventory of APIs, from internally-focused services to externalised APIs for experience and partner integration. As your organisation’s list of APIs grows, it can quickly get out of control. This can lead to API sprawl as your API inventory becomes untrackable.
One way to prevent API sprawl is to leverage an API catalogue to keep track of your API inventory. Let’s explore the details of an API catalogue, discuss the differences between a catalogue and a portal, and then find ways to get control of your API inventory to prevent API sprawl from taking over your organisation.
What is an API catalogue?
An API catalogue is the complete library of APIs that your organisation owns and manages. Catalogues are typically internally facing, allowing your staff and contract developers to browse, discover, and use any available API.
Most API-first organisations also use an API catalogue to track APIs that are still a work in progress. This prevents a team from building a duplicate API when another team is already delivering one.
What is the difference between an API catalogue and a developer portal?
A developer portal is a branded and curated set of APIs targeting specific markets or personas. The portal will offer additional documentation and getting started guides beyond standard reference documentation in an API catalogue.
Contrast that to an API catalogue, which organises and provides structure across all of your APIs in the organisation, even those that are strictly for internal developer use only.
Organising your API catalogue
An organised API catalogue provides a clear structure, discovering APIs possible for development staff. APIs are typically organised by domain area, although there may be other ways to group your APIs in the catalogue.
Without proper management of an API catalogue, the API catalogue will quickly become disorganised; APIs cannot be easily discovered and used by developers, resulting in duplication of effort. Eventually, executives will have no way of identifying the owner of an API or report on the health of a domain’s API surface area.
To maintain your API catalogue structure, define a clear process for adding new APIs. This will ensure API consumers can discover the APIs they need quickly and easily, including those still being designed and developed.
Likewise, manage your URL paths using path prefixes or other URL path naming conventions. This will enforce a domain structure for your APIs and help to prevent duplicate APIs.
Who should manage your API catalogue?
In the early stages of an API program, the API catalogue may be managed by a single person. This may be someone in enterprise architecture or an API centre for enablement (API C4E). Sometimes, a small team of product owners may be responsible for large catalogue areas.
Over time, you may require product owners from each domain to oversee their specific domain area. For large organisations, an additional level of ownership may be required to handle the growing surface area of your APIs.
Some organisations have found benefits in automating the addition of APIs into the catalogue as part of their continuous delivery processes. As API documentation is discovered, such as OpenAPI or GraphQL schema definitions, the API is automatically registered into the catalogue.
Encouraging API reuse through an API catalogue
As the organisation’s API surface area grows, the organisation becomes more modular and composable. APIs become the building blocks for creating new solutions, integrating with new partners, and engaging in new digital channels.
Not all API reuse is the same, however. There are two levels of reuse: local and global.
Local reuse enables a business unit or domain area to leverage its portfolio of APIs and services for reuse. This reuse is focused on integrating APIs to connect new systems to legacy systems, transform data from a legacy data store, or combine it with a third-party system. This is little ‘r’ reuse, as the amount of reuse is limited to the specific domain.
Global reuse helps the organisation benefit from economies of scale by productising APIs for reuse across business units and domain areas. This reuse often extends to business partners and customers. APIs from the catalogue are bundled into an API product, documented and supported as a whole unit. API examples are also provided to focus on the needs of the specific personas or market segments the API product is targeting. This is better considered big ‘R’ reuse, as reuse is focused beyond a particular domain to a broader audience.
Case study of API catalogues in the hospitality industry
A few years ago, I had the opportunity to partner with a global hotel brand as it underwent a digital transformation initiative. During the engagement, we identified a few challenges that required rethinking the API catalogue and portal strategies.
Additional steps
The first challenge was that their API catalogue was contained behind a login screen. This additional step of requesting login credentials to view the list of APIs in their catalogue hindered adoption. We worked toward shifting their API catalogue away from a login screen to an open, internal catalogue of current and upcoming APIs.
This enabled the development staff to consume first and build only when necessary, avoiding duplicate effort and encouraging an API consumes first culture.
Three primary audiences
The next challenge was that they had three primary audiences requiring a different set of APIs. As mentioned earlier, internal developers needed access to all their APIs. We built an API portal that exposed all APIs from their catalogue to the internal development staff to ensure they could find what they needed.
We then built a separate portal for partners who wish to resell room vacancies within 24 hours of the availability. This portal contained a subset of APIs targeted specifically at bulk fetching vacancies and available booking rooms.
Finally, we built a dedicated portal to support the needs of property management as they perform check-in and support requests for their guests. These portals were powered by their API catalogue and customised to address the needs of each developer persona.
Manual processes
The last challenge was to automate the process of deployment. By using the API catalogue, combined with some OpenAPI extensions, we were able to automate the delivery and configuration of APIs on their API gateway. Authorisation and routing rules were embedded into the OpenAPI documents using extensions, which their automation scripts would use to configure and manage the entire deployment process.
As they shifted to an API catalogue approach, they invested in more opportunities as their API platform started to take shape.
From API catalogues to API platforms
When organisations focus on “big ‘R'” reuse, they often discuss managing an API platform that encourages new solutions for their customers and partners. At their core, platforms seek to create an ecosystem within the organisation to support the ever-changing market. In some cases, the ecosystem may extend to customers and partners. An API platform helps to connect and automate communication and collaboration between all parties.
We are seeing the emergence of platform engineering as a means of automating the deployment of APIs consistently. When combined with an API catalogue that lists all available APIs, internal developers become empowered to discover and consume APIs. One or more custom API portals are then offered to externalise their APIs to meet the marketplace’s needs quickly.
Getting started with an API catalogue
You will need an API catalogue if you are starting your API journey or already have a large inventory of APIs. Let’s review some of the key points of this article as we look at the steps you will need to take to get started using an API catalogue:
- Start by organising your APIs by domain area to ensure your entire API portfolio is properly managed.
- Ensure your API catalogue remains up-to-date with the latest APIs by integrating it with the full lifecycle of your API design and delivery process.
- Publish one or more developer portals to meet the needs of partners, customers, and other API consumers in your target markets.
You can unlock the full potential of your APIs with Tyk’s comprehensive catalogue and portal support. Streamline API management, enhance developer experiences, and accelerate innovation – start your free trial and see the difference for yourself.
