Submit support requests and browse self-service resources.
Olaf van Gorp
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.
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:
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:
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.
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.
Access Akana’s Universal API Portal for free, allowing you to easily create, secure, publish, and market your APIs.
Get Akana's Universal API Portal
Technical Sales, Akana
Olaf has over 20 years’ experience with software development and architecture, helping organizations such as Compuware and Capgemini solve enterprise-level integration and governance issues. Olaf has supported the technical sales for Akana API management since 2014, diving deep into security challenges as well as issues specific to financial services, such as PSD2 and Open Banking.