API management platforms play two important and complementary roles, one internal and one external. Inside the organization is where administrators add and manage APIs that are used. Externally the developer portal is where developers can see what APIs are offered, documentation on how to use them, and to get an API developer key that allows API’s to be used. All API developer portals provide these basic functions.
Developer portals have traditionally been created by developers for developers. There was no requirement to think about “the digital experience” even as web interfaces and content strategy became more sophisticated. APIs play a critical role in the digital economy and developers have evolved into customers of API programs. Companies want developers to use their APIs over their competitors. The developer portal is the first touch point developers -- your customers -- will have with your API program.
To get developers interested in your API program you need to present a “World Class Developer Experience” What does that mean? What makes a great developer portal?
- Audience Research - Understanding who your developer is and what they do on your portal. Persona workshops define different motivations that drive developers to use your portal. By knowing your “customers” you can give them what they want, how they want it.
- API Organization - A developer portal is similar to an e-commerce store. Products (APIs) have to be easy to find if you want customers to use them. There are many ways to organize your APIs on the developer portal. A concise API taxonomy can help. Tagging APIs with taxonomy terms creates logical groupings that are easy to search and sort through.
- Well Written Technical Documents and API Specifications - Traditionally, technical documentation is very dense and not well written. Developers tend to be younger and like to consume information quickly. Creating a modern tone for your documentation and rewriting it using a “recipe” with code samples and related visuals developers will be delighted developers and give them more reasons to engage with your APIs. Templates are used to standardize and help your developers write consistent specification documents.
- Design and Page Layouts - A well-polished developer portal depends on the look, feel and layout of the content. We want developers to engage with your APIs, and keep coming back to use them. A beautiful design that showcases your portal and its content and assets is a winning strategy.
- Supporting Content - a developer portal is focused on providing three major things: Available API listings, API specification documents and to give developers API keys. A developer portal is also where the Company API program is marketed to both internal and external consumers of the API program. Managers have a lot to deal with. They have to sell the API program to gain internal adoption and they have to work on gaining external adoption by developers. They have to clearly explain what the program is and why to use it. This is traditional marketing strategy work. Developing a content governance strategy for your developer portal will help keep the marketing messaging consistent.
A world-class developer portal experience has to be well thought out to provide great business value and be maintainable.
Are you in the process of building an Apigee developer portal? Chapter Three are experts in executing the five points outlined in this post. Strategy, writing, design and development is what we specialize in. Let’s talk more about how we can help you.
