How an API portal can accelerate your API initiative

Simply put, An API portal is a catalogue aimed at developers to provide information about APIs. That’s why it’s also known as developer portal. It provides a single point-of-access where developers can find all the information they need to start connecting with your APIs.

A good API Portal provides clear information in a concise manner and lets a developer get started as soon as possible. It’s a quick start guide to all documentation focusing on the essentials for development, like:

• The security mechanism that’s being used
• The policies that are active
• The expected data in the request
• The status codes and/or expected response

But it doesn’t stop there though, there are plenty of other enablers an API Portal provides to API developers:

A self-registration service which developers can use to register their apps, which means retrieving the required security credentials and indicating which APIs will be used by the apps. Imagine if Facebook would have to take a manual action for every website out there that says “connect with Facebook“. Likewise it makes sense that developers can self-create their account on the developer portal to reduce the overhead.

The API exploration service allows for browsing and searching for APIs. This is of course important for developers to select the right API for a specific integration (otherwise they might not know there’s a bulk service).

Other nice-to-haves for developers is when a playground environment is provided, quickly allowing calls to be made before actual code has to be written. This can help to create understanding of the API and what needs to be coded. Another way to get development time up-to-speed is to provide libraries which interact with your API, or by providing sample code. By providing these things developers don’t have to reinvent the wheel for every new integration.

Of course, the API provider is responsible for keeping everything up-to-date. But he also gets advantages from the API Portal. It provides a single point where the API provider can manage everything related to access: approving or rejecting new access requests to the API and revoking existing access. Access to public and private information can be given on an individual level or a role-based model. All of this depends on the needs of the provider and can be a combination of an automatic and a manual process.

You can see the API Portal is the one place where developer-provider interaction can be organized. There is even a possibility for literal communication by providing a forum for the developer to ask questions and make suggestions. For the provider it can be a place to notify the developers of changes, introduce new initiatives or communicate when an API is being phased out. To address the most common issues, a FAQ provides the developers with a quicker answer while alleviating the API provider from having to answer the same question over and over. External resources such as stackoverflow, google blogger etc can also be included when necessary. The developer portal is also the prime location to provide contact information or to make contact forms available.

It’s quite clear why both developers and providers would want an API portal.

For developers it’s a single source for all information required to start development. Of course, this includes all the technical help described in the previous section. But in addition, it’s also a central location which shows all APIs available and which can help select the right API for the job. Both functions of the API Portal can accelerate development and create a useful overview of all APIs for the API providers.

For API Providers, it’s a single point to interact with developers, both for receiving feedback and updating users. Providing all information in one place and automating access management (where possible) will prevent time being lost, which helps focusing on the essentials.

For the company as a whole, it gives a face to your API program, creating visibility to the value of your API program to all stakeholders. In addition, there’s the advantage of having an accurate overview of all APIs the company makes available and for whom they are available.

As you can see, setting up a good API Platform offers a lot of advantages, but it also takes effort. Effort to make all resources available, to keep them up-to-date, to engage with the community etc. New roles within your organization will presumably be needed. And the way of working when exposing APIs will have to change if you want to keep your API Portal in pristine condition. Of course, when things are tackled in a smart way, the costs can be minimized and, as mentioned earlier, could in fact make other tasks lighter.

One way we advocate is to link your API Portal with your API Management platform. For example, the OpenAPI specification is in some way available in the API management platform. A lot of this data is needed in the API Portal. Making this link, automatically ensures the most up-to-date configuration, and you don’t have to manually align everything. The same thing applies to other things which might be configured in the API management platform such as rate limiting, authorization type and CORS settings.

The API Management platform also has a lot of real-time data which can be useful for API consumers. By sharing how many calls fail, you can provide insight in a failing process. For example, if almost all calls succeed, the error is most likely on consumer side, or vice versa.

When choosing your supplier for the API Portal you don’t need to choose the same as your API manager (not all API manager platform suppliers necessarily provide an API Platform). While it’s often technically possible to go a different route, there are some arguments to be made to sticking to a single supplier. First of all, you might lose some functionalities as not all aspects of the portal and/or manager can be integrated, negating some of the advantages above. Second, there might be a substantial extra cost due to extensive customization by the vendor for the integration of the API Management platform or the gateway.