How to make your APIs more discoverable

API discoverability is a key aspect of any API management initiative. The discoverability of an API directly impacts its adoption and usage. A typical big enterprise with multiple development teams might build hundreds of APIs that they would want to reuse internally or share with partners that build complementary applications. If the teams are not able to discover existing APIs, they might build a new API with the same functionality. It might lead to a duplication of efforts and underutilization of the existing API. It is also an unscalable practice to contact the API developer each time someone wants to use the API.

There needs to be a better and more hands-off way for internal teams and partners to discover and understand the usage of these APIs without directly contacting the developers who built them. API discoverability does not just mean making it easy to find an API by providing an inventory (though this is the first and most important step you should take). It should also address some key aspects that are important for an API consumer, such as understanding the API through documentation, request and response format, sign-up options, and the business terms and conditions (in case of a partner) of using the API.

Developer portals to the rescue

Developer portals provide a convenient and scalable way to achieve this. Developer portals enable API consumers to search, filter, learn, understand, and sign up for the APIs they are interested in. Organizations can customize developer portals based on their goals and intended audience. These portals provide an easy way to build an API inventory catalog with search and filtering capabilities.

In the subsequent sections, we will see how we can build a dynamic API catalog that addresses all of the above-mentioned use cases with Red Hat 3scale API Management.

Building an inventory of APIs

First, let's build an inventory of all the APIs the developer portal can access. This implementation is based on the APIs.json initiative. This would be a JSON that multiple portal elements can access and get all the information they need to show about the APIs.

However, for different reasons, you would not want to expose all the APIs managed in 3scale API Management via this JSON. API providers can add additional checks and rules to restrict which APIs are exposed and which are not. In the following example, we will only expose the APIs when they have some basic information about them, like rate limits, pricing, support, etc. APIs that do not have this information about these aspects will be deemed ineligible for sharing and will not be discoverable. We will add this information to our APIs using the features options in application plans, so any APIs with no associated features will not be discoverable.

Note: This is a custom condition for discoverability that we set; we can always change these rules based on our processes and business use case. For example, you can remove all these checks and conditions and make all the APIs managed through 3scale API Management discoverable.

Follow these steps to create our APIs.json:

1. Create a new section: In the 3scale API Management admin portal, navigate to Audience → Developer Portal → Content. Click on the New Page drop-down and select New Section (Figure 1).

   

2. Name the section catalog and change the partial path as shown in Figure 2. Click Create Section. This is the section where we will organize all the files we need for this exercise.

   

3. Create a new page with the title apis.json. Make sure the Layout field is empty, Liquid is enabled, and that you choose the right path and section. Copy and paste the code provided in this link (see Figure 3).

4. From your 3scale API Management admin portal, navigate to Developer Portal → Drafts; then, click Publish All.

   

5. Navigate to the /catalog/apis.json endpoint of your developer portal. You should see a JSON with the list of APIs and the associated details, as illustrated in Figure 5.

   

Building an API catalog page

The API catalog page is a key component of API discoverability. We will build a section on our developer portal that lists all the APIs and makes them searchable (see Figure 6). API consumers can perform a text search to find the APIs, filter APIs based on different criteria, click on the APIs to get more details, etc. This is how consumers will find the APIs they need.

Follow these steps to create our API List section:

1. Create a new page with the title API List, as shown in Figure 7. Make sure you choose the right path and section. Copy and paste the code provided in this link. You do not need to modify the Layout and Liquid sections for this.

The API details section

After searching for the API on the list page and narrowing down the API, an API consumer would like to learn about the chosen API. This details page we are about to build now serves that purpose. This page contains various elements such as interactive documentation to understand details like the API request and response model, sign-up options, subscription plans, terms and conditions, and support options.

Follow these steps to create our API details section:

1. Create a new page with the title API Details, as shown in Figure 8. Make sure Liquid is enabled, and you choose the right path and section. Copy and paste the code provided in this link. You do not need to modify the Layout section.

   

2. Navigate to Developer Portal → Drafts and click Publish All (Figure 9).

   

Find APIs

Finally, follow these steps to see the catalog in action.

Note: You can also verify the dynamic nature of the catalog by adding a new API product in the 3scale API Management admin portal, with application plans and some associated features in the applications plans that are enabled and a documentation file with the same system name as the API.

1. Navigate to /catalog/list endpoint of your developer portal, and you should be able to see a list of APIs that you can search and filter using the search bar and filters under "Categories" on the righthand side (Figure 10).

   

2. Click on an API of your choice to find more information about the API, such as interactive documentation where you can make sample calls to the API, sign up for subscription plans, etc. (see Figure 11). You can also add more sections and information based on what you think your API consumers would like to know about the API. API providers can easily add additional assets such as images and CSS files to customize the whole developer portal to be in line with their brand.

   

Conclusion

API discoverability must be a key aspect of any organization's API strategy. API product teams would benefit by thinking about this right from the early stages of building the API rather than being an afterthought. API providers can create an effective self-service API program by incorporating aspects of API discoverability such as search, filter, categorization, documentation, usage rules, terms and conditions, etc.

Through this exercise, you learned how to create a dynamic and interactive API catalog using Red Hat 3scale API Management that will enable the API product teams to improve the discoverability and usability of their APIs and thus facilitate the adoption of their APIs. If you want to create a similar experience on your developer portal, the links to all the files used in this demo are available on GitHub if you would like to create a similar experience on your developer portal.

Get started with Red Hat 3scale API Management

Red Hat 3scale API Management makes it easy to manage your APIs. Share, secure, distribute, control, and monetize your APIs on an infrastructure platform built for performance, customer control, and future growth. You can place 3scale API Management components on-premise, in the cloud, or on any combination of the two.

Red Hat OpenShift API Management is a hosted and fully managed version of 3scale API Management. If you are interested and want to give it a try, you can do so by visiting the product page.

Last updated: September 19, 2023