Success of an API Program for an enterprise depends on the proper planning to build the right API at the right time to meet the current and growing needs of the consumers. APIs that power the digital business should not only be built correctly with clean and well documented interface, but should also be published and socialized with a developer community that can help in the adopting the APIs at pace. A good API developer portal helps to easily onboard developers onto the API program. In this chapter we would look at the role of an API Developer Portal in API Lifecycle and what should be the features of a good Developer Portal so that it can attract developers and facilicate their onboarding onto the enterprise API program.
The API Lifecycle
The life of an API starts with designing the right interface using an API-First approach. Once the interface is designed and documented, it is built and deployed on an API platform that provides the runtime infrastructure. The API platform should also help publicize and socialize the APIs with the developer community to accelerate their adoption. To support the evolving requirements, older versions of APIs should be slowly deprecated and retired, giving way to publish newer versions of the API. An API developer portal plays a vital role in managing the lifecycle of the API by providing a mechanism to publish and socialize APIs.
Publishing and Sharing APIs
A well-built API will not fetch the desired business benefits unless it is publicized. People—especially developers—looking to build apps using APIs need to know about it. So an enterprise needs to have a mechanism to publish the details of the APIs and provide a platform for the developers to easily find and use the APIs. Developers need to know the details about the API.
An API should be well documented to provide information about the endpoint, the input/output parameters, the SLAs, monetization model/rate plans, and other information. The API provider needs a social enterprise API platform to publish information about the APIs, whether the API is for internal or external use.
It needs to be marketed well. An API provider needs a platform to market his API with a powerful search-driven catalog that offers social features such as ratings, reviews, likes, and more. The API needs to be published in a catalog with appropriate descriptions and tags to easily search for potential consumers.
After developers have found an API in a catalog, they would like to know its fitness for their app development. This is where developers browse through API documentation, blogs, and forums to read user feedback on the API and evaluate it. They would like to know how interested the community is in the API to better understand the level of adoption and support for the API. An active community allows developers to ask questions and get honest feedback from fellow developers who are using the API. Good feedback in forums helps drive faster adoption.
The Importance of the API Developer Portal
A developer portal provides the platform for an API provider to communicate with the developer community. It helps communicate static information about the API, such as documentation and terms and conditions for use. It can also include dynamic social content contributed by the developer community, such as forums and blogs.
Creating a good API is only a small step in building a successful API program. API providers need to expose and publicize information about the API, provide documentation to educate developer communities about the API, and provide a platform to easily register developers and their apps. Developers and users of the APIs should be able to provide feedback, get support, and make new feature requests that can help the APIs to evolve. App developers should also be able to submit and share their own content for others to use.
An API portal is a single point of information for an app developer looking to use APIs in building an app. In addition to providing documentation for the API, the portal should provide a platform that allows users to easily play around with and test the APIs; this helps developers better understand its usage in building apps. Embedded API test consoles and smart docs generated from API specifications can be used for testing the API interface within the portal.
A developer portal should provide developers with analytics information for API usage. App developers should be able to monitor the API usage pattern for their apps. API analytics information can include traffic trends, API performance metrics , and error rates for the API and apps.
Supporting App Developers
App developers are the real users of the API. Innovative apps built by app developers increases API adoption and usage. Hence, as an API provider, it becomes even more important to effectively support the app developer community to accelerate the adoption of your API. An API provider should provide support to app developers to drive the API’s social adoption. The support provided can be in various forms.
Good documentation to easily understand the API interfaces
A test bench to play with the API and understand its behavior
SDKs and code samples that developers can readily use in their apps to invoke the API
A Q&A forum for developers to help each other by answering questions asked by others
An indexed forum to search for errors, issues, or questions and get immediate answers to already solved problems
An API provider should put lot of effort and time in building a thriving community. The right investments in building the app developer community with the rights folks can help pay enormous dividends later and make the API program successful. An API Developer Protal should provide the following social collaboration features to support the developer comnunity.
Invitations
Invitations are a popular way to socialize your APIs. They are an easy and effective way to build a community for API users. A developer portal should facilitate sending invitations that create a community of interests around the API. Any user—an API or app developer, or a business administrator—should be able to invite others to start using or following an API. You can encourage people to invite their contacts too. This can help build a huge social community connected to the API.
Social Forums
A social forum helps app developers share their experiences with using APIs. It can connect developers who are building apps with the APIs. They can discuss best practices for using the API, as well as any limitations and how to overcome them. They can post their comments and ideas, ask questions, and even raise support ticket with the API provider. The view available to an app developer can depend on the assigned role. An administrator might be able to see all issues logged and all unanswered questions; whereas an app developer may only see the answered questions and the check status on the issues that they logged. As the community around the API matures, the forum might act as a platform where API users and app developers answer questions or make comments on questions asked by fellow users.
An enterprise API platform needs to be social. App developers and API users should be able to follow APIs, apps, business organizations, developer groups, or other users. A personalized dashboard for each app developer should provide them an aggregated view of all items of interest. It should provide a centralized dashboard where they can keep track of what’s going on with everything that they are interested in.
Federated Developer Communities
The success of an API initiative depends on its adoption by the developer community. A developer portal allows developers to sign up for the API program and get access to the API. The portal helps API providers build their own developer community. But a federated developer community might be a better idea. With a federated approach , developers of other API providers, who are partners or are like-minded, may want to share the same API keys with developers. So if a developer signs up with a company’s API program and obtains an API key, the same API key can be used to access APIs provided by other partners of the company.
An enterprise API program should support the concept of an API provider federation. This brings together communities by providing developers with access (through proper authorization) to any API from any provider by using a single API key. This helps API providers easily extend the reach of their APIs to a wider community of developers. However, all of this first needs a deeply federated trust and permissions model to be established between the API providers. The model should allow API providers to opt in or out of the federation model and to choose the partners with whom they want to federate.
Types of Portal Users
There are three types of portal users: app developers, the API team, and the API product owner. The app developersuse the APIs to build apps. They refer to the API portal to learn more about the APIs that they can use for developing apps. They look for API documentations and a sandbox environment to try out the APIs. They register for an account in the portal, register their apps that will use the APIs, review the terms and conditions for API usage, interact with other developers in the community through forums, and view statistical information about their app usage on a dashboard.
The API teamis the provider of the APIs. They create the developer portal to publish information about their APIs for the developer community. The API team sets up the portal and the workflow for developers to register and obtain an API key. The workflow may be simple automatic approval or it might involve manual verifications and approvals. The API team sets up the API portal to do the following:
Automatic or manual approval for API key generation
Publish and maintain API documentation
Provide and maintain a forum for app developers to connect with other developers in the community
Provide a test bed for app developers to test the API interface through an embedded test console
Provide contact and support for app developers
Enforce a role-based access control mechanism for developers to access various features in the portal
Customize email notifications sent to administrators and developers for user creation, app registration, and approval
The API product owneris the person or organization responsible for the productizing the APIs. They are responsible for identifying the APIs to be built based on market research and user stories. They work with sales, marketing, and other stakeholders to create an API product that will sell. They are responsible for understanding what the app developers want. They help to translate the business requirements into terms that the API team can use to actually build APIs that will sell. The API product owner would be responsible for the following:
Defining how APIs should be packaged into a product
Defining the process and rules for app approval
Define the pricing and billing plans for the API products
API Developer Portal Features
As an API provider , it is important to understand the features that the API portal should have. The portal should attract app developers and provide all the necessary information that they might be looking for to get started with using the API. The following are some of the features to consider while building or customizing a developer portal.
User registration and login: The app developer should be able to easily sign up for the API program and start using the APIs. The registration process should be simple and easy. Requiring a lot of information to register or a complicated registration process may annoy developers and hold them back from signing up for the API program. Hence, the developer registration form should be simple and easy. A minimalistic approach for user registration is recommended. When a developer registers, the approval process can be automatic or manual. In either case, an email should be sent to the developers that confirms registration. The administrator should also be notified of developer registration and be provided with a link to approve, if so required. In a manual approval process, an email should be sent to the developer once their registration request is approved. The login process after the registration should be easy but secure.
User management: A developer portal administrator should be able to create and edit users. Administrators may directly create developer accounts through the portal. Upon successful registration, the portal should send an email to the developer informing her that the account is created. The administrator should be able to modify the status of the developer from active to blocked if so required, or update a developer’s profile information. Role assignment is yet another aspect of user management. Admins should be able to assign roles to registered users to control the privileges and access rights of the user based on custom roles, and signed-in and anonymous users.
API documentation: The portal should be the source of all information about the APIs. It should provide all documentation for the API, such as interface specifications, FAQs, tutorials, examples, and sample code. Getting started and how-to guides on using the APIs help accelerate API adoption. Including request and response messages using real-world examples helps developers easily understand the API interface. The API documentation can also include a reference guide that explains common vocabulary, data formats, best practices, common HTTP response codes, and error messages.
API test console: A console for developers to test an API helps them explore and play around with it without writing any code. Developers can use the console to submit a request to the API and view the response. A smart doc for an API also helps developers easily learn how to use the API.
Forums and blogs: Community-contributed content , such as threaded discussion forums and blogs that describe the developers’ experiences, help build an engaged developer community.
App registration and key management: When an app developer wants to create an app using the API, he needs to get an API key. For this, developers need to register their apps with the API provider in the portal. The portal should allow developers to register their apps. The approval for the app registration can be automatic or manual. In an automatic approval, the API key is generated immediately upon registration. The approval process can be manual if any background verification needs to be performed before approval. In a manual approval, the API key is generated only after the app registration has been reviewed and approved by the administrator. An administrator may also revoke keys or regenerate new ones.
Email configuration: The API portal should send email notifications when developers sign up for the API program or register their apps. The API portal administration should provide the facility to configure the email templates with the content and format of the emails to be sent. The admin should also be able to configure when emails should be sent to developers.
Dashboard: App developers like to view statistical information about their apps and the APIs used by their apps. They like to know the number of users using their apps, the number of calls made by their apps, and the various APIs and methods used by the apps. The developer portal should provide a dashboard for app developers to view all of this information and much more.
Support information: The API support information in the portal should provide the developers’ contact information so as to reach in case of any queries or issues with using the API. The contact information can be a phone number or an email address. The support page in the portal can include quick API status information. The status could be active, under maintenance, deprecated, or retired. The support page can also include FAQs, notices, or coming soon information of interest to the developer community. Notices could cover latest updates or activities related to the API. Coming-soon information provides a list of upcoming API features.
Search: A search facility within the developer portal is very useful feature. It helps developers quickly search for information. They can search for APIs of interest, or for specific information within the API catalog, or specific content within the forums or blogs.
The Relationship Between a Developer Portal and an API Gateway
The API developer portal is the door to an enterprise’s API program. It lets developers sign up and register their apps to use the APIs. An API gateway provides the API runtimes. An API key is generated on successful registration and is stored in a database that is referenced by the gateway for API key validation. Not only that, all app attributes, developer information, and details about the organization are provided as part of the onboarding process is stored in the database that the gateway references for validation purposes.
The portal acts as a client for the API gateway to store and fetch API-related information. Normally, the portal makes REST API calls over HTTP or HTTPS to communicate with the gateway. For example, when a developer registers a new app, it makes a request to the gateway to send information about the app to the gateway data store. Every instance of an API developer portal must be associated with an API gateway that hosts the APIs and provides the runtime support. Both the portal and the gateway can be deployed on cloud or on-premises. A hybrid deployment model in which the portal is on the public cloud while the gateway is set up on-premise is also possible.