Submit support requests and browse self-service resources.
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.
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.
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.
Your portal needs to make it easy to find APIs. There are three key requirements for an internal developer portal to support this.
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.
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.
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.
There are lots of elements to facilitate the easy use of APIs. There are several key requirements for internal developer portals to support this.
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.
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.
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.
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.
The developer portal needs to be strongly integrated with the API gateway infrastructure. This enables a number of important capabilities:
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.
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:
And Akana makes it just as easy for developers to use APIs with:
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
Explore additional resources: