While most organizations have matured in developing the glue between their information and application systems via APIs, many often overlook how to deliver and expose those APIs to their respective consumers.

Reusability and adoption are the driving factors for a healthy ROI from an API, but they are harder to obtain than you may think. This is often due to the provider suffering from a lack of visibility of the API catalogue, poor documentation, and/or poor self-service facilities for API consumers.

A lot of work goes into onboarding new API users. Developer consumers must first discover the API, then assess if it provides the services they are after. The API must be high quality, stable, and comparable or better than similar services on the market before they recognize it’s worth their money and time investment.

An API portal aims to streamline this process. As its name suggests, an API portal bridges the gap between API consumers and API providers. In this article, we’ll see what an API portal should encompass, and how it can help API providers plug the re-usability and adoption gap to provide a platform to successfully promote their APIs.

Promotion: 6 Traits of a Quality API Portal

Like any other type of product, an API requires an effective marketing strategy. This arises in the form of an API portal to support some key promotional activities. Irrespective of your API being public, partner, or private, the content should be rich and informative. Often supported by an API product owner, API evangelist, internal developers, and content writers, a developer portal is comprised of the following six core units.

1: Catalogue

An API Catalogue describes what APIs are available for consumption, listing them all and providing ample descriptions for every method. Documentation should also provide the authentication and authorization mechanism, use cases that describe potential business contexts, and live real world implementations when possible.

2: Lifecycle Information

An API portal should also describe API lifecycle information, clearly identifying:

• Deprecation policy: When and in what circumstances the API would be retired.
• Release schedules: Frequency of major and minor releases.
• Migration processes: Ways to migrate between different API versions for an existing consumer.
• Versioning methodology: What is the specific versioning method? For example, minor versions may be backward compatible, whereas major versions may require code modifications for consuming applications.
• Latest test results: Where possible, API providers should also share up to date results from functional testing.

3: Legal

Your developer portal must also cover legal territory. To ensure you communicate the means and processes of consuming the APIs, describe the eligibility criteria. These are the terms and conditions to qualify to be API consumer. For example, accessing your service may be as simple as creating a user account and receiving API keys. Or, there may be a complex approval process involving legal teams. Whatever your specific process is, articulate it clearly and use visual diagrams when appropriate.

4: Pricing Information

If the APIs are not free for use then you must describe the monetary cost involved at the individual API level as well as for bundled APIs. Describe any complex pricing models that may exist. For example, it may be that the consumer pays upfront for a limited usage, is charged on a per call or resource basis, or pays a fixed rate for unlimited usage. Some programs bundle the API into larger packages, offering more cost effective rates in doing so, or otherwise provide lucrative discounted offers throughout the API lifecycle. The Service Level Agreement and implications of SLA breaches should also accompany the pricing information.

At times it may be too cumbersome to manage the pricing information as developer portal content, rather, some groups prefer that the API portal is integrated with a separate product catalog that specializes in the product offering and pricing management.

5: Training Resources

Add training materials such as tutorials and how tos to your developer portal. Onboarding material doesn’t have to be limited to text — consider training videos and other rich multimedia content. It’s also useful to provide an API sandbox so that potential consumers can make sample requests and view responses. Ensure your training resources cover things like:

• Demonstrate how security tokens are provided
• Pre-requisites to be satisfied before the API invocation
• Sample request and response for API invocations
• Error scenarios and how they will be handled by the API
• Software Development Kits and libraries to kick start API consumption.

6: API Health Insights

To increase consumer confidence, a provider should make their API performance transparent. Listening to the API heartbeat with real time monitoring, current API usage, number of subscribers, average response time, and other insights can act as a huge confidence boost. The portal should also provide a detailed list of issues and expected resolution timelines; it’s beneficial here to allow consumers to vote to help prioritize issues.

API Adoption: Onboarding New Users

Once publicized, API providers must equally focus on API adoption, because in the absence of quality, consistent customer service, usage will plummet. Below is a list of items API providers should concentrate on to improve the developer onboarding experience — remember, providing as many self-service options as possible will make your life easier.

Developer Onboarding Actions

The API portal should be the primary channel for onboarding API consumers. This may involve different processes depending on the type of API — for example, it may be as simple as signing up using social logins, or it may involve a more complex account creation process involving an approval hierarchy and system updates.

In either case, the API portal should either provide or integrate with a workflow system that can be used to implement different processes for consumer onboarding. From the provider viewpoint, the following actions may need to be taken during the consumer onboarding process. Some may need to be performed manually, while some should be done automatically:

• Approve/decline user registration
• Suggest a modification to the user registration information, like changing the organization code
• Validate the information provided during user registration
• Send user registration invitations
• Assign a community administrator to the organization
• Creation and enforcement of varying account levels for different developer portal roles, such as moderator or administrator
• Send notifications, such as marketing collaterals or maintenance updates
• Or define other custom workflows for the API consumer application process.

From the consumer perspective, their needs during onboarding are a little different. Here are some of the self service functions an API consumer will need to perform on the portal:

• Register on the API with (or without) a social account
• Sign into the portal, once registered
• Reset login credentials and update account information
• View a personalized landing page
• Register their application(s)
• Generate credentials like API keys
• Interact with API documentation
• Test API functionalities, view sample calls/responses
• Invite fellow application developers to collaborate.

Onboarding Various Consumer Types

Above are very generic use cases that may not be applicable to all types of API consumption scenarios. To understand specific needs based on various target consumer bases, let’s see how onboarding changes for public users, partners, and private users.

1. Public User

With public users, consumer onboarding can be done using social logins or through a direct signup with the provider. Often in the public realm, the provider offers a freemium usage model. In doing so, it’s extremely important that quotas are enforced, so that providers can monetize their services correctly.

If the APIs are supposed to be used only by certain web domains, then there should also be enforcements on cross origin resource sharing. Public providers must have strong security, accepting security tokens like API keys during the API invocation for identification. The API portal should allow users to generate these API Keys, and optionally asks users to provide application details along with domain names from which the APIs will be consumed.

Below are some specific public API scenarios for different industry sectors where having a developer portal is key:

• Health Care: APIs that provide data on medical facilities, medical professionals, pharmaceutical details, or statistics can be either free or paid depending upon the provider. As the APIs provide information rather than functionality, these APIs often don’t require a sandbox, and the end user application can be directly integrated with production APIs.
• Banking: APIs that provide banking information to aid better customer experiences. Examples are APIs to provide branch locations, interest rates, product offers, and forex rates. As the information is publicly available and read-only there is no need for a sandbox. Production APIs can be made directly available via an API portal. Quota control and enforcement needs to be in place to manage traffic surges.
• Telecommunications: APIs to provide publicly available information like plan offerings, pricing details, mobile phone details, spam filters, geo location, analytics, recharge service, content services, or others. A use case example is an application to help user find best offers.

Some of these API types, like a recharge service API, will require a sandbox environment. Using an API portal, providers can provision user access to both sandbox and production environments, which use different endpoints. In this scenario, it’s best to keep separate API keys for sandbox and production environments to avoid any confusion.

2. Partners

With partner integrations, consumer onboarding is not as straightforward. The API consumer needs to be a trusted partner, and therefore must have an agreement in place to use the APIs to meet a common business objective. In this scenario, API consumption may happen over a dedicated communication channel like a virtual private network, or over public channels like the Internet.

An organization with a matured onboarding process for partners will have automated workflows with an API portal as the starting point of the approval process. As workflow fulfillment may take days or weeks to complete, the API portal should provide status updates on the onboarding progress.

For an example partner integration, take payment APIs that facilitate transactions for bank customers. As financial institutions open their payment gateways via APIs, they are often made available on a need-to-know basis for select partner financial institutions. Offering businesses and consumers a fast, versatile, data-rich payments system for making everyday payments requires financial institutions to provide infrastructure through which consumers can integrate easily.

In this exchange, a significant challenge is securing the API invocation over a public channel as well as taking care of nonrepudiation requirements. Such environments require a sandbox to enable integration exercise between the institutions. In partner environments, an API portal must facilitate the following unique actions to support partner onboarding:

• Manage API consumer registration via invitation only
• Customize the API catalogue for invited partners
• Allow partner to securely upload/modify their public certificates or other security credentials to be used during API invocation
• Enforce stricter user registration processes.

3. Private Users

As private APIs are internal to organizations, it makes sense to span the API portal across all production and nonproduction environments. Developers and architects like to see APIs across all environments and to also view how their APIs are tracking within the development process.

As there will be some APIs open for integration with all applications, and some high value APIs accessible to only certain applications, private developer portals often require a mix of public and partner onboarding styles. The API portal should be able to differentiate between these various internal APIs and different workflows for users.

Subscription Management

Users of an API portal should be able to manage their subscription irrespective of the subscription being paid or free. The API portal should also allow users to monitor the API usage at their organization level and application level, and to upgrade or downgrade their subscription plan. If the API usage is paid then it should provide users a facility to check and generate invoices as well as make invoice payments.

As an API product manager, some of the generic use cases in regards to subscription management would be:

• Define subscription plan for API consumption
• Define payment channels
• Send API subscription specific marketing collateral
• Send notification related to API subscriptions

As an app developer, some required actions would be:

• Being able to provide applications (from registered apps) which would be consuming the subscribed APIs
• Request a custom quotation for an API subscription
• Monitor and track API usage
• Perform payment and generate invoices

Community and Forums

A quality API portal also allows users to share their API usage experience and to make suggestions to improve the APIs. Moderators should be able to create forums, invite users, and mediate forum discussion. Forums can also be one way for the provider organization to alert and notify API consumers of any changes or updates.

Conclusion

The developer portal is truly the intersection between the API provider and the developer consumer. By addressing the specific needs of both the API provider, as well as the API consumer, we can develop helpful API portals that improve the onboarding experience.

In terms of implementing an API portal solution, it’s difficult to find third party products that tick all the boxes, but at the same time, homegrown solutions may not be ideal — a lack of integration with underlying API gateways and the high cost of building a content management system from scratch could be big deterrents.

In choosing a tool to use, API providers should seek out a balance by selecting out-of-box products that provide good integration with underlying API platforms, but at same time are flexible with the specific registration workflows, identity systems, and product catalogues that are unique to their API type.