Internal APIs Need a Developer Portal

By Parna Bhattacharya

When we on Google Cloud’s Apigee team talk to enterprises working to build their API programs, the developer portal is often a critical part of the conversation.

As destinations for APIs, documentation, testing tools, community support, and more, developer portals are recognized as de facto storefronts for external-facing APIs, such as those available to partners or to third-party developers.

With external APIs, developers play a crucial role in the value chain, taking the data and functionality that APIs express and modularly combining and recombining them into new services and digital experiences. These developers are a special kind of customer for the enterprise, and just as companies encourage consumers to adopt digital services by making sign-up as easy and friction-free as possible, companies need to make their APIs simple for outside developers to access and use. Therefore, it’s essential to give these developers a first-class experience — which is what a portal helps to do.

But what about internal APIs that are never meant for public exposure, such as those used by a human resources department to connect systems and for employee-facing applications? And what about internal developers leveraging APIs within the enterprise? Should businesses invest in building portals for them?

Yes, they should.

Internal developers working purely with internal-facing systems and digital assets have many of the same needs as their counterparts outside the organization. Internal developers can occupy a similar role in leveraging software to create value. Unless an enterprise wants its internal talent to waste time duplicating work instead of using APIs that already exist, its developers need easy and secure discovery, support, and testing tools — just like their external counterparts.

For example, Service NSW, an Apigee customer that provides government services to people and businesses throughout New South Wales, adopted an internal developer portal “to bring together all our APIs in one place, and to improve visibility so that various product teams can discover and use them,” said Rahul Dutta, Product Director at Service NSW.

He said that compared to the agency’s old system for API distribution, which was often siloed and reliant on ad-hoc processes, the portal helps internal developers to reuse existing APIs and for the organization to develop software more efficiently and apply more consistent governance and security policies.

As this example suggests, a company shouldn’t burden its own talent with a worse experience than it provides for external talent. As former Microsoft CEO Steve Ballmer famously said, “Developers! Developers! Developers!” — and today’s business leaders should take his chant to heart, regardless of whether the developers are inside or outside the organization.

Four Challenges API Portals for Internal Developers Help Solve

Discoverability

Often, enterprises possess a large number of internal APIs — sometimes hundreds or even thousands. Consequently, when teams cannot easily find an existing resource, they end up building duplicate functionality — which can be a costly and time-wasting inefficiency.

Internal API portals can help by providing a central catalog of APIs that teams can check before attempting to engineer their own solutions. Reusing existing APIs can accelerate project completion, and providing internal developers the ability to learn and test APIs can reduce barriers to consumption and reuse. If employees are sending emails to hunt down an API or its documentation, the enterprise is not helping them to do good work.

Collaboration and Innovation

Because of their modularity, APIs enable teams to be more responsive to changing customer needs. They can create new communication pipelines and new ways of solving complex problems as teams leverage one another’s work. Challenges such as conflicting priorities never completely disappear, of course, but by making it easy for internal developers to adopt the API platform, a company can make it easier for teams to function in autonomous, agile ways, and to minimize dependencies among various teams’ work.

Security

There is no reason why the API security standards and controls should be more relaxed for internal APIs than for the external APIs. An internal developer portal can provide a secure way for internal developers to register an application and to access API keys and tokens. Without a portal, developers might have to resort to dangerous workarounds like sharing API keys over email or other public channels! Centralizing APIs in a portal and managing them via an API platform also enables an opportunity to clearly enforce consistent access controls.

Internal Can Become External — so do Internal Right From the Start

If an API is useful to developers inside an organization, there’s a good chance it might be useful to outside developers too. This means that API products that are exposed internally today might be great candidates for partners or public consumers in the future. Indeed, high internal consumption of an API might help an enterprise identify the asset as the next one that should be opened to the outside. If the enterprise were not managing and monitoring its internal catalog, it might never have made the connection.

Bottom line, when internal APIs are designed and managed with the right security controls, documentation, and user-oriented attitude from the beginning, a great deal of technical debt can be avoided later.

[Ready to learn more about empowering developers? Read our free eBook, Creating World-Class Developer Experiences.]