Get organised with an API catalogue
Whether your APIs are for internal use only or for public consumption, an API catalogue plays an essential role in ensuring they are discoverable. The benefits of an API catalogue include greater efficiency within your business, easy access management and superior monetisation. Below, we’ll explain what an API catalogue is, why you need one and how to create one.
What is an API catalogue?
An API catalogue is an organised library of available APIs. It is searchable by both humans and machines, meaning it needs to be highly organised, with APIs categorised to make them easy to find. Most organisations embed their API catalogue within their developer portal.
API catalogues can be both private and public. A private API catalogue contains APIs that are solely for use within your organisation. A public API catalogue, as the name implies, contains APIs for external consumption. Both can deliver distinct advantages to your business, as we’ll discuss below.
According to SoftwareAG, a whopping 86% of organisations are utilising APIs in all or the majority of digital transformation projects. Meanwhile, the Enterprise Strategy Group reports that 64% of organisations expected to rely on APIs for most or all of their internal applications by 2023. These figures make a strong case for the use of private API catalogues, even when businesses don’t plan for external parties to consume their APIs.
In addition to detailing your APIs in your catalogue, you can add documentation, service level agreements, tests, examples, security policies and other artefacts to aid consumers in discovering your APIs and integrating and using them swiftly and efficiently.
Benefits of an API catalogue
An API catalogue is an important tool for the strategic management, promotion and sharing of your APIs. The headline benefits include improved discoverability, greater collaboration and enhanced governance. Let’s look at the factors that support this.
Increased visibility
Private API catalogues can help internal teams and departments discover APIs of which they might otherwise have been unaware. This is particularly useful in large enterprises, where there can be a lack of visibility between different departments. A well-organised API catalogue can reduce duplication of effort and thus enable greater efficiency within the business.
Public API catalogues also deliver increased visibility, enabling third-party consumers to connect with and consume your APIs. This greater visibility can lead to higher adoption rates of your API products and, thus, more income for your organisation.
Organisation and efficiency
What is API catalogue management good for? Well, API catalogue tools used by internal teams can introduce organisation and efficiency to the way you manage your APIs. For example, APIs in your catalogue can form the basis of organisation-wide standards, which is particularly useful when it comes to matters such as API security. An API catalogue can also help your internal teams to identify redundant code.
For external consumers of your APIs, the organisation and efficiency that an API catalogue can deliver doesn’t just boost discoverability. It can also foster developer communities that are helpful in shortening feedback loops between you and your consumers, thus enabling you to enhance your support offering.
Better security
It’s surprisingly – and worryingly – easy for a business to lose track of its APIs. Old versions that weren’t taken offline or decommissioned properly can represent serious security vulnerabilities, with forgotten zombie, rogue or shadow APIs with outdated security mechanisms providing unauthorised access to company data and systems. Maintaining a catalogue of all APIs can avoid such occurrences, as everything can be monitored and visible in one place, resulting in enhanced security.
Creating an API catalogue
It’s not difficult to create an API catalogue. Let’s run through the three steps you need to take.
Step 1: Gather APIs and documentation
The easiest way to create your API catalogue is to use a service catalogue API or an API management tool. This enables the programmatic creation and management of your catalogue with minimal effort. Be sure to include documentation to underpin the usability of your APIs and make them discoverable.
Step 2: Set up the catalogue structure
Setting up the catalogue structure requires some thought. An API catalogue can simply be a list of APIs on your website. However, embedding your catalogue within your developer portal is the more common approach.
Where this gets complicated is when you have more than one developer portal. For example, some businesses have separate private and public developer portals. Organisations may also have multiple API gateways. The API catalogue structure needs to take this into account, with the catalogue able to span multiple portals, gateways and so on.
You also need to think about the organisational structure of your catalogue and ensure that it is both machine-searchable and human-searchable. Organising your APIs by type can make a lot of sense, as can including APIs in multiple categories when their functionality warrants this. You could also organise your APIs by access level, with one set for developers, another for admins and so on.
Keep discoverability top of mind when making your structural decisions to ensure this focus isn’t lost.
Step 3: Publish the catalogue
Once your catalogue is ready, you can publish it via your developer portal using your chosen API management tool.
API catalogue best practices
Follow these best practices to ensure you get the best out of your API catalogue:
Do regular API audits
Your API catalogue shouldn’t be left on the (virtual) shelf to gather dust as soon as you’ve published it. Keep it clean and organised through regular audits to ensure your APIs are current and up to date.
Include documentation and examples
As mentioned above, include documentation, examples and other artefacts that will support the easy adoption and integration of your APIs. Doing so will make them easier to consume and provide a better developer experience.
Make it easy to search and filter APIs
The easier it is to find your APIs, the more people are likely to adopt them. As such, ensure it is easy for both humans and machines to search your catalogue and filter your list of APIs based on differing needs.
Provide access control settings
Decent API catalogue tools will allow you to set access permissions based on different roles. Ensure you take advantage of thi so that your APIs are only accessed by those with the appropriate authority to do so.
Using the Tyk API management platform for creating an API catalogue
If you’re using the Tyk API management platform, you can benefit from an API catalogue as part of the API developer portal. You can use this to manage which of your APIs developers can access.
The API catalogue is separate from the API list section on your Tyk Dashboard so that you can expose only the APIs you wish to via the catalogue. You can control access to these via policies, enabling you to give access to a bundle of APIs exposed as a single interface.
If you’re using Tyk as an API gateway for microservices, you can use the catalogue to publish your external APIs however you wish them to appear. For example, you could manage four separate microservices APIs in your Tyk Dashboard, but combine them under a single security policy in your catalogue.
Examples of API catalogues
Companies around the world are using API catalogues to expose their APIs and enable consumers to find the products they need. Let’s look at a couple of well-known examples.
Google Maps platform
The Google Maps API platform contains various APIs and services, each of which serves a specific purpose. The platform includes detailed documentation, with a wide range of usage options and pricing models available, from free tiers to usage-based payment. Google also provides software development kits (SDKs) and libraries for various programming languages.
Amazon Web Services (AWS)
AWS provides the AWS Service Catalog to enable organisations to create catalogues of products approved for use in AWS, with the AWS Service Catalog API providing programmatic control over all end-user actions.
Common challenges with API catalogues
Creating an API catalogue can present challenges. Let’s look at a couple of examples.
Keeping documentation up to date
An API catalogue needs to be kept up to date, including the documentation. Inadequate documentation can hinder developers’ productivity and make your APIs harder to integrate, so you need to allocate time and resources to keeping your documentation current.
Security concerns
Ensure all APIs in your catalogue adhere to the latest security best practices, including authentication, authorisation and encryption. This is essential for data protection and for maintaining trust.
Community engagement
Building an active, engaged community around your API catalogue can boost its success, so you’ll need to allocate resources to this. An API catalogue open source approach, where developers share their experiences and feedback and create a collaborative community, is the goal here.
Wrap up
A well-organised API catalogue can reap benefits ranging from greater efficiency to higher income. We’ve covered how you can create a catalogue, including how Tyk can support you in your microservices architecture.
Why not explore some of the other benefits of Tyk while you’re here?
