API Life Cycle Basics: Portal

A coherent strategy to delivering and operating API portals is something that gets lost in a number of the API operations I am asked to review. It is also one of the more interesting aspects of the successful strategies I track on, something that when done right, can become a vibrant source of information, and when done wrong, can make an API a ghost town, and something people back away from when finding. As part of my research I think a lot about how API portals can be used as part of each APIs lifecycle, as well as at the aggregate levels across teams, within groups, between partners, and the public.

The most common form of the API portal is the classic public developer portal you find with Twitter, Twilio, Facebook, and other leading API pioneers. These portals provide a wealth of healthy patterns we can emulate, as well as some not so healthy ones. Beyond these public portals, I also se other patterns within the enterprise organizations I work with, that I think are worth sharing, showing how portals aren’t always just a single public destination, and can be much, much more.

  • Individual Portals - Considering how developers and business users can be leverage portals to push forward conversations around the APIs they own and are moving forward.
  • Team Portals - Thinking about how different groups and teams can have their own portals which aggregate APIs and other portals from across their project.
  • Partner Portals - Leveraging a single, or even partner specific portals that are public or private for engaging in API projects with trusted partners.
  • Public Portal - Begin the process of establishing a single Mutual of Omaha developer portal to provide a single point of entry for all public API efforts across the organization.
  • Pipeline Integration - How can BitBucket be leverage for deploying of individual, team, partner, and even the public portal, making portals another aspect of the continuous deployment pipeline.

Portals can be used as the storage for the central truth of OpenAPI, and their JSON schema. They can be where documentation, coding, tooling, and other stops along the life cycle live. They also provide for an opportunity for decentralization of API deployment, but done in a way that can be evolved alongside the existing CI/CD evolution occurring within many organization, as well as aggregated and made available as part of company wide public, partner, or private discovery portals. Portals, can be much more than just a landing page, and can act as a doorway to a vibrant ecosystem within an organization.

I admit, it can be tough to turn a landing page for a portal into an active source of information, but with the right investment over time, it can happen. I maintain almost 200 separate portals as part of my work as the API Evangelist. Not all of them are active and vibrant, but they all serve a purpose. Some are meant to be static and never changing, with others being more ephemeral and meant to eventually go away. While others, like the home page for each stop along my API life cycle research staying active for almost eight years now, providing a wealth of information on not just a single APIs, but an entire industry.