The Universal API Portal: Comprehensive Access to All Your Enterprise APIs

Over the past years, many enterprises have embarked on an API program as the principal means of data integration. The underlying strategy typically proposes the (re-) use of APIs as one of the guiding principles. Software developers working on code that involves integration with other applications are required to look for existing APIs that will provide them with the necessary data and/or functionality. Reuse of APIs is highly effective for a number of reasons: it avoids duplication of code, allows for governed access to systems and code, etc. – in-short, it reduces cost and risk while accelerating time-to-market.

Given the immense popularity of APIs overall, the approach clearly is successful. However, there’s a flip side to this success, which is the relatively uncontrolled proliferation of APIs that can often be seen across the enterprise. Thus, the management of APIs becomes a necessity to ensure the continued success of the API program and underlying strategy.

An important aspect of this “management” is facilitating API adoption. After all, any successful API program starts with effective API adoption. This means that APIs must be easily discoverable, once found, they should be easily understood. For developers, implementing the API into their code should be more or less self-explanatory.

The Importance of a Comprehensive API Catalog

To support effective API discovery, a comprehensive catalog of APIs is an excellent starting point. Not only will developers (and other API stakeholders) have a single location where they can find any available API they are looking for, but they can also expect to find all the necessary details to help them understand the workings of the API and how to integrate it into their code.

An API catalog is best presented in an API Portal. A well-implemented API Portal offers an optimized user experience that addresses the needs of all API stakeholders. Client software developers are an obvious stakeholder group, but so are application product owners and architects – and they may have a need for distinct information. In summary, an API Portal is much more than a listing of APIs and a representation of their technical interface. It should present all information that helps stakeholders to effectively find and review the API they’re looking for and, once validated, help utilize the API.

Having a single API Portal as a centralized location for API information is highly recommended, yet it will only be truly beneficial if the API Portal provides a comprehensive catalog of all available APIs, regardless of ownership, deployment platform, etc. 

This aspect is likely to be more challenging and has both technical and organizational implications, in particular:

• How should ownership of the API Portal be organized? In principle, ownership should be delegated to a distinct, central entity.
• How to get details from all available APIs into the Portal? Preferably, the API Portal should be able to import API definitions from anywhere.
• How to ensure you’ve covered all? Ideally, API publishing should be part of automated CI/CD processes. This also helps to ensure that published API details are kept in sync with the actual runtime API.

Effective API Identification

To help stakeholders effectively identify the API they are looking for, the API Portal should first offer effective search and filtering capabilities. Categorizing APIs using a stakeholder-approved taxonomy of API metadata is a great help.

What ultimately helps stakeholders to determine whether an API is fit for purpose is its available documentation. To this day, the lack of sufficient documentation is reported as one of the main obstacles to effective API consumption. Often, API documentation consists of no more than the functional interface presented through a Swagger/OAS-based overview. Yet, to facilitate a proper understanding of the API, documentation should include at least:

• Description of use cases that the API intends to support.
• Detailed overview of any constraints that apply to API access and usage.
• Details on any security requirements that the consumer should satisfy.

Authorized Portal Access

Comprehensive, enterprise-wide visibility on APIs is an irresistible capability, but comprehensive access does not imply unlimited or unconstrained access. Some APIs may be visible to all, whereas others may only be visible to users with specific authorization.

For example, internal users will typically have access to a wider range of APIs than external ones. A special case is managing visibility for unmanaged API endpoints that are merely meant as building blocks for API products that are yet to be published. Visibility of those endpoints should be limited to a privileged, internal user group only.

In summary, the API Portal should have an authorization scheme in place to ensure APIs and their published details are only visible to designated users.

Conclusion

For a successful enterprise API program, providing comprehensive API visibility is an indisputable first condition that must be met, as it will give stakeholders ready access to APIs that may fit their purpose and, as such, will enhance API adoption and reuse.

Having an API Portal as an enterprise-wide-looking glass that provides visibility on all available enterprise APIs is very helpful, but it will typically not sufficiently address additional management aspects like consumer management, runtime access control, traffic management, and monitoring. For these, highly reliable API management platforms remain an indispensable part of the full API management puzzle.