Why You Need an API Developer Portal for API Discovery

Enterprises increasingly rely on APIs to connect applications and data across business lines, integrate with partners, and deliver customer experiences. According to TechRadar, today the average enterprise is leveraging a total of 15,564 APIs, up 201% year-on-year.

As the number of APIs continues to grow, the complexity of managing your API portfolio increases. It gets harder to discover and track what APIs are available and where they are located, as well as find documentation about how to use them. Without a holistic API strategy in place, APIs can proliferate faster than your Platform Ops teams can manage them. We call this problem API sprawl and in a previous post we explained why it’s such a significant threat. In this post we explore in detail how you can fight API sprawl by setting up an API developer portal with help from NGINX.

Build an Inventory of Your APIs

Ultimately, APIs can’t be useful until they are used – which means API consumers need a way to find them. Without the proper systems in place, API sprawl makes it difficult for developers to find the APIs they need for their applications. At best, lists of APIs are kept by different lines of business and knowledge is shared across teams through informal networks of engineers.

One of the first steps toward fighting API sprawl is creating a single source of truth for your APIs. That process starts with building an inventory of your APIs. An accurate inventory is a challenge, though – it’s a constantly moving target as new APIs are introduced and old ones are deprecated. You also need to find any “shadow APIs” across your environments – APIs that have been forgotten over time, were improperly deprecated, or were built outside your standard processes.

Unmanaged APIs are one of the most insidious symptoms of API sprawl, with both obvious security implications and hidden costs. Without an accurate inventory of available APIs, your API teams must spend time hunting down documentation. There’s significant risk of wasteful duplicated effort as various teams build similar functionality. And changes to a given API can lead to costly cascades of rework or even outages without proper version control.

Techniques like automated API discovery can help you identify and treat the symptom of unmanaged APIs. But to solve the problem, you need to eliminate the root causes: broken processes and lack of ownership. In practice, integrating API inventory and documentation into your CI/CD pipelines is the only approach that ensures visibility across your API portfolio in the long term. Instead of having to manually track every API as it comes online, you only need to identify and remediate exceptions.

Streamline API Discovery with an API Developer Portal

Streamlining API discovery is one area where an API developer portal can help. It provides a central location for API consumers to discover APIs, read documentation, and try out APIs before integrating them into their applications. Your API developer portal can also serve as the central API catalog, complete with ownership and contact info, so everyone knows who is responsible for maintaining APIs for different services.

A core component of our API reference architecture<.htmla>, an effective API developer portal enables a few key use cases:

• Streamline API discovery – Publish your APIs in an accessible location so developers can easily find and use your APIs in their projects
• Provide clear, up-to-date documentation – Ensure developers always have access to the most up-to-date documentation about how an API functions
• Ensure proper versioning – Introduce new versions of an API without creating outages for downstream applications, with support for versioning
• Generate API credentials – Streamline the onboarding process so developers can sign in and generate credentials to use for API access
• Try out APIs – Enable developers to try out APIs on the portal before they integrate them into their projects

As part of your API strategy, you need to figure out how to maintain your API developer portal. You need an automated, low‑touch approach that seamlessly integrates publishing, versioning, and documenting APIs without creating more work for your API teams.

Create a Single Source of Truth for Your APIs with NGINX

To enable seamless API discovery, you need to create a single source of truth where developers can find your APIs, learn how to use them, and onboard them into their projects. That means you’ll need a developer portal – and up-to-date documentation.

API Connectivity Manager, part of F5 NGINX Management Suite, helps you integrate publication, versioning, and documentation of APIs directly into your development workflows, so your API developer portal is never out of date. In addition to making it easy to create API developer portals to host your APIs and documentation, API Connectivity Manager lets you add custom pages and completely customize the developer portal to match your branding.

Let’s look at how API Connectivity Manager helps you address some specific use cases. Refer to the API Connectivity Manager documentation for detailed instructions about setting up a developer portal cluster and publishing a developer portal.

Automatically Generate API Documentation

There is often a wide gulf between the level of quality and detail your API consumers expect from documentation and what your busy API developers can realistically deliver with limited time and resources. Many homegrown documentation tools fail to integrate with the development lifecycle or other engineering systems. This doesn’t have to be the case.

How NGINX can help: API Connectivity Manager uses the OpenAPI Specification to publish APIs to the API gateway and automatically generate the accompanying documentation on the developer portal, saving API developers time and ensuring API consumers can always find what they need. You can upload OpenAPI Specification files directly via the API Connectivity Manager user interface, or by sending a call via the REST API. This makes it easy to automate the documentation process via your CI/CD pipeline.

To publish documentation in API Connectivity Manager, click Services in the left navigation column to open the Services tab. Click the name of your Workspace or create a new one.

Once you are in the Workspace, click API Docs below the box that has the name and description of your Workspace (example-api in the screenshot). Simply click the  Add API Doc  button to upload your OpenAPI Specification file. Click the  Save  button to publish the documentation to the developer portal.

Ensure Proper Versioning

Version changes must always be handled with care, and this is especially true in microservices environments where many services might be interacting with a single API. Without a careful approach to introducing new versions and retiring old ones, a single breaking change can lead to a cascading outage across dozens of microservices.

How NGINX can help: Using OpenAPI Specification files with API Connectivity Manager enables easy version control for your APIs. In addition to setting the version number, you can provide documentation for each version and manage its status (latest, active, retired, or deprecated).

To publish a new version of an API, click Services in the left navigation column. Click the name of your Workspace in the table, and then click the name of your Environment on the page that opens. Next, click the  + Add Proxy  button. From here you can upload the OpenAPI Specification, set the base path and version to create the URI (for example, /api/v2/), and input other important metadata. Click the  Publish  button to save and publish your API proxy.

The original version of the API remains available alongside your new version. This gives your users time to gradually migrate their applications or services to the most recent version. When you are ready, you can fully deprecate the original version of your API. Figure 2 shows two versions of the Sentence Generator API published and in production.

Generate API Credentials

To drive adoption of your APIs, you need to make the onboarding process as simple as possible for your API consumers. Once users find their APIs, they need a method to securely sign into the developer portal and generate credentials. These credentials grant them access to the functionality of your API. Most often you’ll want to implement a self‑managed workflow so users can sign up on their own.

How NGINX can help: API Connectivity Manager supports self‑managed API workflows on the developer portal so users can generate their own resource credentials for accessing APIs. Resource credentials can be managed on the portal using API keys or HTTP Basic authentication. You can also enable single sign‑on (SSO) on the developer portal to secure access and allow authenticated API consumers to manage resource credentials.

To quickly enable SSO on the developer portal, click Infrastructure in the left navigation column. Click the name of your Workspace in the table (in Figure 3, it’s team-sentence).

In the table on the Workspace page, click the name of the Environment you want to configure (in Figure 4, it’s prod).

In the Developer Portal Clusters section, click the … icon in the Actions column for the developer portal you are working on and select Edit Advanced Config from the drop‑down menu. In Figure 5, the single Developer Portal Cluster is devportal-cluster.

Next, click Global Policies in the left navigation column. Configure the OpenID Connect Relying Party policy by clicking on the … icon in the Actions column of its row and selecting Edit Policy from the drop‑down menu. For more information, see the API Connectivity Manager documentation.

Try Out APIs on the Developer Portal

One way you might measure the success of your API strategy is to track the “time to first API call” metric, which reveals how long it takes a developer to send a basic request with your API.

We’ve established that clear, concise documentation is essential as the first entry point for your API, where your users get a basic understanding of how to work with an API. Usually, developers must then write new code to integrate the API into their application before they can test API requests. You can help developers get started much faster by providing a way to directly interact with an API on the developer portal using real data – effectively making their first API call without writing a single line of code for their application!

How NGINX can help: Once you enable SSO for your API Connectivity Manager developer portals, API consumers can use the API Explorer to try out API calls on your documentation pages. They can use API Explorer to explore the API’s endpoints, parameters, responses, and data models, and test API calls directly with their browsers.

Figure 7 shows the API Explorer in action – in this case, trying out the Sentence Generator API. The user selects the appropriate credentials, creates the request, and receives a response with actual data from the API.

Summary

APIs are crucial to your organization. And the first step towards governing and securing your APIs starts with taking an inventory of every API, wherever it is. But API discovery is only part of the solution – you need to build API inventory, documentation, and versioning into your development and engineering lifecycle to address the root causes of API sprawl.

Start a 30-day free trial of NGINX Management Suite, which includes access to API Connectivity Manager, NGINX Plus as an API gateway, and NGINX App Protect to secure your APIs.