Building a Developer Portal?
Here are four key questions to answer first
In collaboration with Apigee, for about a year now we at Pronovix have been custom-fitting the default Drupal-based Apigee developer portal to Apigee customers' individual requirements.
We’ve noticed some patterns emerging regarding the types of developer portals that organizations need and how they can address those needs using Apigee’s developer portal.
We have been experimenting with a series of targeting questions to help our customers think through what kind of portal they actually need, and what kind of features it should incorporate.
Thanks to that effort, we’ve identified the four most important questions—the ones that show the common set of requirements our customers usually request. The answers to these questions help identify the purpose of the developer portal and help to facilitate the decision-making process.
Which audience does your developer portal target?The answer to this question defines whether your portal will be open to the wider public or only to a certain group of people (your partners or your internal developers, for example). Is your site fully accessible to whomever visits, or are there barriers hiding any of the content?
If it isn’t open for everyone, your portal must have a reliable and flexible access control system. Often companies have partnerships that only grant selective access to certain APIs; not all their APIs are available to all their partners. With an access control system, it’s possible to manage API visibility without exposing the existence of anything else but what is accessible.
There are companies that use developer portals only internally. In these cases, the portals are not available for anyone outside of the company but may still need an access control system to manage the API availability for different developer teams within different business units.
Developer portals open to the public or to partners often have custom visual elements such as logos and brand colors to make it easier to recognize them. In the case of portals for internal use, branding is usually less important.
How many APIs does your developer portal handle?The number of APIs you offer might be an important factor in the decision-making process about developer portals. If the portal provides access to hundreds of APIs throughout an organization wherein many teams are building their own APIs, then that portal will also act as a catalog of those APIs.
In these cases, it‘s crucial to make it possible to find (and use) the APIs across the various teams. The whole purpose of APIs is to interconnect and to make it possible to use each other's data (read our blog post ”What is an API?” to learn more). Portals with lots of APIs have custom search functions to make the site-wide search easier and to provide better search results.
If a portal manages only a handful of APIs, then a sophisticated search solution is not that important. A small handful of APIs could be well presented in groups based on their purpose.
What’s your API strategy and how can your developer portal support it?Do you want to charge a price for API usage? If so, you need a dashboard where administrators can track the usage of APIs (calls and responses, for example). This analytical data is also useful if your business model is based on fixed prices—or if you don’t charge for API usage at all, because you can keep an eye on your API traffic.
With the Apigee Edge Monetization extension, you can track API usage and even bill your customers for using your services.
What content do you provide along with your APIs?Companies want to expose not only APIs but other related content on their developer portals. Writing, publishing, and improving documentation, blog posts, and onboarding materials on a portal is a complex workflow and might involve a lot of people (technical writers, copywriters, marketing people, editors).
Even if you have only a couple of technical writers working on API documentation, you need the infrastructure to create and publish the content. The more varied content the content on your portal, the more complex the infrastructure.
The answers to these questions help lay out a clear path you can follow during the planning phase. Coming up next, we’ll discuss the most common requirements that arise when implementing developer portals.
Kristof Von Tomme is CEO of Pronovix, and István Zoltán Szabó is the company's content strategist. Pronovix builds custom-fit developer portals in Drupal. Sign up to get a copy of the Pronovix white paper "Developer Portal Components."