11436 SSO

API Best Practices: Developer Portals

How do organizations enable wide adoption and consumption of their APIs?
Oct 07, 2016

Previously, we discussed best practices around deployment models for API platforms. Here, we’ll cover key features of developer portals and considerations for organizations who use them.

As an API provider, you want prolific adoption of your APIs by developers. As organizations put in place developer portals, the key questions they wrestle with include:

  • How do I make APIs easily discoverable and what API related content and packaging do I need to make app developers successful?
  • How do I manage the onboarding of application developers?
  • How do I manage identities and access permissions of my API team members, internal app developers and external/partner app developers for the developer portal?

How to publish easy-to-use APIs

APIs are easy to use for developers when they can be easily discovered through popular channels like search engines. Interactive API documentation and sample request/response patterns key for ease-of-use, play a role, too.

Many organizations use the Open API (formerly known as Swagger) specification to create interactive API documentation. It enables developers to not only understand the API specifications, but also try, test, and debug API calls.

Sophisticated API management platforms enable automatic generation of API documentation and publishing to a developer portal. The up-to-date documentation ensures app developers can easily discover the right APIs and get started.

An API management platform also enables developers to provide feedback, make support and feature requests, and submit their own content that can be accessed by other developers.

APIs as products

Organizations can simplify API consumption and enforce API best practices by treating APIs as products. It’s a way to package APIs into bundles and attaching rate limits and pricing models. The API product feature available in API management platforms enables the creation of different tiers of offerings for different sets of users, using the same set of APIs and associated resources.

This feature also enables organizations to quickly try out new business models while keeping the underlying APIs and resources stable.

How to onboard app developers effectively

There are couple of ways to onboard application developers onto your developer program and get them started on building apps using your APIs. Organizations choose the appropriate method depending on their business model, target developers and company compliance policies.

Fully self-service

App developers can sign up, register their apps, get their app keys and get started—all without any approvals from the portal administrator. Internal developer portals are set up in this mode, typically integrated with corporate active directory systems. Organizations that have public APIs and want to engage large developer communities take this route, too. In most cases, the administrator is notified by email about the signups to track usage.


In this mode, app developers register on their own, but there is an admin approval step in the process. Upon admin approval, the app developer can register apps, get keys, and access all the documentation. Organizations that want to expose APIs to strategic partners often to use this mode.


The portal administrators sign up the application developers in this process. It’s an uncommon approach, but in certain highly sensitive cases, organizations use this mode to restrict access to APIs.

Most API management developer portals provide these options out-of-the-box. Organizations can choose the appropriate onboarding process depending on their needs.

How to manage user identities

A variety of developers use an organization’s portal, including the API team and internal  or external app developers. An organization has a variety of of options when it comes to managing users’ identities in the developer portal.

Built-in directory

Most developer portals provided by API management vendors have a built-in module to store and manage user identities.Typically, organizations use this capability to store external app developers’ information.

Single sign-on integration

Many enterprises have an active directory (AD) and use an active directory federated service (ADFS) provider like Okta, Siteminder, or Ping Identity. To enable SSO using ADFS, API management developer portals enable easy integration with an enterprise’s ADFS via SAML protocol. This is the most common implementation for internal app developers and API team members.

How to manage user access permissions

When an API is published to the developer portal, it’s important to manage access permissions for different sets of users. Depending on the situation, an API or API product would have different access permissions.

Internal only

This set of APIs on the developer portal are only visible to an organization’s API developers. You use this level of visibility when you API team is testing new APIs on the developer portal before public availability.


This set of APIs are visible to developers that have explicit permission granted during their app registration process. Organizations use this mode when they are sharing with external partner developers and don’t want to necessarily expose these API or specific resources to all developers.


These set of APIs are visible to all registered developers. Organizations with public API programs or purely internal developer programs use this mode for production-ready APIs.

How to empower app developers with data

Many organizations provide their API users and app developers insight into their specific API usage, performance metrics, and revenue measures as part of the developer portal experience.

Developer analytics available in API platforms provide out-of-the-box usage analytics to track the usage of  APIs, identify volume patterns, and enhance their API consumption experience.

Performance analytics like API latency times and error rates provide visibility into API SLAs and support app developers’ API debug issues.

In developer portals that include monetization, app developers can track revenue, billing, and other business metrics, all in one place.

A key part of a digital initiative’s success is fast adoption and prolific usage of APIs by app developers, both internal and external. Thinking through various factors like interactive API documentation, onboarding processes, and management of user identities and access permissions upfront will go a long way to setting up an organization for success.


Creating World-Class Developer Experiences