Structure of a Developer Portal

A developer portal is the ‘shop front’ for a system’s API. It contains API Documentation – that is, the technical information required to understand and integrate with an API.

A developer portal should be self-service and make it easy for developers to get started. It should make the system’s API visible to enable internal and external developers build innovative solutions. Thus the strategic goals of a developer portal are to enable self-service integration and to serve as an innovation hub.

Across the developer documentation space, slightly different terminology is used to define the structure of developer portals. I will define here the terminology I use.

  1. Overview / Landing pages: These answer the question “What is this ?“. They provide API summaries and explain the benefits and capabilities of the API.
  2. Tutorials: These answers the question “How do I get started?”. Tutorials to provide step-by-step instructions on how to start using the API resources. They are clear how-to’s that are interactive and focus on a specific part of the platform. This is a crucial part of onboarding developers to the system.
  3. Use Cases: Show developers some solutions they can build with the API, to get the developers thinking. This is meant to inspire developers and provide ideas of possible solutions that can be built with the API. For example, here are Uber’s use cases.
  4. Showcase: Exhibit work partners have done using the API. Here is Visa’s showcase. This is related to Use Cases, and some organisations combine them.
  5. Conceptual Docs: These answer the question “What are the important things I need to understand about how the system works?“. This section introduces the developer to the domain and model of the system.
  6. Guides: This answers the question “How do I get X done“. They explore typical problems and use cases a developer will experience when using the platform.
  7. API Reference: This section answers the question “What are all the details I need to know to perform a particular operation?“ . It provides the HTTP routes, requests and responses, and the meaning of domain objects and attributes. Tools exist that can generate this from Open API Specification documents for REST APIs, GraphQL Specifications document for GraphQL or Async API specification documents for message based systems.
  8. API key generator: This answers “How do I get security credentials to make API calls to the system ?”
  9. API Policies: This section provides legal information on the terms of use of the API. It answers the question “Can I trust this API?”.
  10. Sandbox Environment : A sandbox environment allows developers to play with the system in safe way, that has no impact on the production system. The portal should provide details on how to connect to the Sandbox environment.
  11. API Explorer: This section answers the question “How can I quickly play with the API as a new user?“. It’s an interactive API console for developers to make sample calls to the developer sandbox environment and see responses. For some REST APIs, this is combined with the API Reference.
  12. Changelog / Release Notes: This section answers the question “What has changed in the API since the last release that I need to know about?“
  13. Support: Support contact details. This can also include things like support forums.
  14. Status: API uptime monitoring.

References

  1. Developer Portal Components – API Documentation Patterns. By Kristof Van Tomme and Kathleen De Roo.
  2. API Developer Portal Best Practices – Yos Riady

Leave a Reply