Key Requirements For an Internal Developer Portal

Your internal developer portal is the key to API adoption success. But what does it take to have a good internal developer portal? That's what we break down in this blog. 

What Is an Internal Developer Portal?

An internal developer portal is exactly what it sounds like. It's your internal API portal where developers can create, find, and use APIs. The goal of an internal developer portal is to make it easy for developers to find and use APIs.

What Makes a Good Internal Developer Portal?

A good internal developer portal makes it easy to find and use APIs.

This table summarizes the requirements for features that enable a good internal developer portal. Keep reading to learn more about each feature in full — or jump ahead to the section that interests you most. 

1. Finding APIs

Your portal needs to make it easy to find APIs. There are three key requirements for an internal developer portal to support this.

Public/Enterprise Search

Search engines have had a massive impact on the way we work. The idea of connecting to a special purpose system to try and find assets (services, APIs, document types, etc.) feels like it belongs in a different decade.

For an externally-facing API, one of the main roles of the developer portal is to market the API — including extensive search engine optimization. This applies to internal APIs, too. An enterprise needs an effective internal search system.

Portal Search

In many cases, finding the right API is a question of being able to search through the hundreds or even thousands of interfaces available.

The internal developer portal needs to provide filtering (by tag or taxonomy) as well as free text search of name, description, endpoint, interface, payload schema, and even discussion forums. This is much more important for internal API initiatives than external. There will typically be orders of magnitude more internal APIs than those facing external consumers.

Hierarchical Browse

The idea of browsing through an API catalog based on a formal taxonomy has become increasingly irrelevant with the power of search — especially when combined with simple filtering.

However, enterprise developer portals often leverage a hierarchy to model their organization, team, and project structures both for delegated admin, and simplified access control. Some developers might only be able to see APIs defined within the scope of their project. And there may be workflow processes for API publication and consumption.

NOTE: Portal search is often important — even for external developer portals that leverage public or enterprise search engines. In many cases the external search will get you to the portal, but not necessarily to the specific resources you need.

2. Using APIs

There are lots of elements to facilitate the easy use of APIs. There are several key requirements for internal developer portals to support this. 

API Documentation

The internal developer portal needs to do much more than publish a technical descriptor document (OAS/Swagger, RAML, WADL, WSDL). It needs to allow API developers to provide detailed scenario documentation, descriptions of how the API security model works, code samples, possibly even SDKs, and much more.

It should also not be limited to just one descriptor language. It should be able to publish API specifications however the app developer wants to consume them.

Provisioning and Access Workflow

The portal should provide workflow mechanisms for approving or rejecting requests from developers to access the portal itself — as well as processes for requesting app access to APIs. 

Versioning and Lifecycle Management

Over the last few years, governance has become a dirty word, especially when applied to SOA programs. Even so, the core concepts of versioning and lifecycle management remain extremely important.

A good internal developer portal will provide control over which APIs are published, how they are published, and when and how they are versioned. It will also ensure that it presents the right version of an API to app developers and will allow developers to choose the version in which they are interested.

Remember: Managing the API lifecycle is important.

Social Interactions

Given the drama surrounding social media at the moment it may seem strange to talk about the importance of social interactions in an API portal. What this refers to, however, is the need for app developers to get help from the API provider and the broader community as they work to build applications that consume APIs.

They also need the ability to follow APIs and API developers to ensure that they stay informed about what’s happening with the APIs they use.

Gateway Integration

The developer portal needs to be strongly integrated with the API gateway infrastructure. This enables a number of important capabilities:

1. Key provisioning and management: API and app keys that are presented to users and used to identify apps and APIs must be shared with the gateway infrastructure.
2. Immediate configuration updates: When a user’s app is granted access to an API, the gateway needs to know that the app’s keys, secrets, certificates, etc. can be used to authenticate the app and validate contracts for access control, per app throttling, SLA management, reporting, and more.
3. Monitoring data: API and app developers should be able to see charts and reports, and access transaction and debug logs for their APIs and apps. API monitoring requires strong integration with the gateways allows the portal to surface real-time operational data to developers and DevOps teams.

Dynamic Content

Inside the enterprise, an internal developer portal will be used to support hundreds or thousands of APIs. And a typical externally facing portal — or API marketplace — will often have only a small handful of APIs. This means that the kinds of heavy-lifting often required to publish an API externally (this commonly involves what is essentially building a custom website for each API) is not practical.

When an API developer creates an API and adds appropriate documentation, it should immediately be published (subject to workflow of course) into the portal for app developers to find and use. Content cannot be static because the volume of change will overwhelm a typical web publishing team.

A key part of this content worth its own mention is the documentation. API documentation should reflect the exact interface that is hosted on the gateway. Whenever an API developer publishes or updates an interface, this should simultaneously affect the actual API endpoint, and the documentation of this API. This documentation should be published in a standardized format (e.g., Swagger), ideally with a built-in test client so that app developers can experience that actual API through the documentation.

The sheer number of APIs and other assets that will be published through the portal means the portal UI needs to be designed for scale. Simple things, like any lists, must be generated by searches, and no lists should appear in static navigation or other static pages.

The effective use of a fit-for-purpose internal developer portal can make all the difference between a failed initiative and a massively successful internal API program.

Build Your Best Internal Developer Portal

To build your best internal developer portal, you need the right features. And the Akana API platform delivers them all.

With the Akana developer portal, your developers can find APIs with:

• Public/enterprise search
• Portal search
• Hierarchical browse

And Akana makes it just as easy for developers to use APIs with:

• API documentation
• Provisioning and access workflow
• Versioning and lifecycle management
• Social interactions
• Gateway integration
• Dynamic content

See for yourself how Akana enables the best possible internal developer portal — as well as external portals. Watch our on-demand demo to see how. 

▶️ WATCH A DEMOTRY AKANA NOW

👉 Become an Expert

Explore additional resources:

• API Basics
• API Lifecycle