APIs are Products — and Products Need a Store

By Gitesh Koli

In my work consulting with large enterprises on their digital transformation and IT modernization efforts, I often see companies interested in consolidating their application programming interfaces, or APIs. The appeals of doing so are obvious: a well-organized catalog of APIs can improve business agility and software development efficiency by decreasing software bloat and increasing reuse of corporate corporate assets, for example, and it can also be leveraged for new partnerships and business opportunities.

But I sometimes see enterprises struggle as they pursue these benefits, often because they have not fully considered their APIs as products. With the mindset that APIs are products that represent a business to developers, the imperative for delivering a world class API portal — the “store” for your API products — may become a priority that can help organizations curate and consolidate APIs as well as deliver a world class experience for developers.

Organizing APIs can be a Challenge

Broadly speaking, APIs are how software talks to other software, and many big companies already have hundreds, if not thousands, of them. An application’s functionality may involve a variety of systems — modern microservices running in the cloud, old monolithic applications, and everything in between. These systems weren’t all necessarily built to communicate with each other, and most developers aren’t fluent in the details of each system type — which is why APIs, which mask this complexity behind an interface developers can work with, are so important.

Needless to say, if APIs are important, organizing and managing them is important too — and for many businesses, this presents challenges.

Most big legacy enterprises are used to working in silos; one team creating APIs might not be aware of APIs being created by other teams throughout the organization. Many companies are moving away from these silos because they cannot support methodologies that match the pace of modern digital business, such as creating applications by assembling digital assets from disparate systems and software that have been created by multiple teams. But even as companies modernize, the lingering impacts of old internal silos may be hard to detect and eradicate.

Silos block teams from seeing what other teams are doing. In most siloed organizations, work is inevitably and needlessly duplicated as one team builds an API that already exists in some other team’s catalog. Businesses often want to consolidate their APIs so developers from many teams can use and reuse the APIs for new purposes — but to do so, they need to weed out the duplicates.

Moreover, because individual siloed teams tend to create APIs according to team members’ personal preferences, a given team’s APIs might not be easy for developers from other teams to consume. Security protections might have been applied inconsistently or neglected altogether. If some of the APIs can’t be easily leveraged for new uses, API consolidation is not simply a matter of cataloging all the APIs various silos have produced — it’s also about knowing a well-designed API from a poorly-designed one.

To meet these challenges and modernize for today’s API-first environment, enterprises need their APIs to be discoverable and to provide a consistent, secure experience for developers throughout their organization — and potentially even externally.

A product approach to API management and an API developer portal are essential ingredients in this process.

APIs are Products

APIs have been around a long time, and for much of their history, they were a relatively anonymous part of the middleware stack, used to expose and integrate systems. Some IT professionals may still think of APIs in these terms — but that significantly undersells how APIs are used by today’s enterprises and developers.

Rather, APIs should be thought of as software products that allow developers to leverage digital assets.

The Google Maps API lets developers build mapping and navigational capabilities into maps, for example. The Twitter API lets developers create applications that let users sign in using their Twitter accounts. Companies such as PayPal offer APIs so it’s easy for developers to build financial functionality into their applications. And many companies have hundreds of internal APIs that developers within the company use, both to do things more efficiently within the organization and to make new services and digital experiences for customers. Increasingly, companies are mixing their internal APIs, which represent their core competencies, with those of APIs from third parties in order to create richer, more personalized, and more useful services.

What does it mean to treat an API as a product?

It means treating developers, whether internal or external, as customers. APIs should be designed for easy and intuitive consumption, not just to expose systems, and they should be supported with documentation and sample code to get developers up and running within minutes even if they are new to the API. Enterprises should apply full lifecycle product management to APIs, whether collecting data to iterate their products as developers need change or applying common security precautions — such as OAuth, bot protection, and continuous monitoring — to all APIs.

Types of API Products

APIs may be intended for different users or purposes, and they should be monitored and managed to ensure they are being used as intended. Broadly, the three types of API products are:

• Public: The API is available for anyone to consume, e.g., a branch locator API.
• Private: The API is available to internal developers or select partners but not to outsiders, e.g., an API to find out the availability of a company’s financial advisers or APIs that are specially created for partner needs.
• Internal: The API is available only to certain employees within the enterprise, e.g., an HR database API that provides access to employee information.

Many enterprises know public APIs should be delivered via an API portal. If you think of developers as customers, the portal is the store.

But too many businesses also give internal developers a second-rate experience, saddling them with manual approval processes, missing documentation, and other productivity-killing frustrations. All APIs should be managed as products, and all developers should get the productivity boost that a self-serve developer portal can facilitate.

API Portal Tips

So if businesses need API portals, what should those portals include? As a final word of advice, here is a checklist of some of the features and resources enterprises should include to position their developer portals for success:

• API Directory: This is where developers start exploring.
• Documentation: Documentation helps ensure that the value proposition of the API is clear and that developers understand how the API is meant to be consumed. Is there a list of documented APIs that need to be called in a specific order for a given result? Are mock screens offered to help developers visualize what is expected? The better documented an API, the easier it will be for developers to leverage that API.
• Sandbox Environments: A sandbox makes it easy for developers to start using and testing APIs. APIs within the sandbox can return mock responses or may point to a staging environment without an real customer data. Sandbox environments not only enable developers to experiment with APIs in a no-risk scenario but also enable enterprises to introduce, test, and learn from new features before launching them as completed products.
• Community: The portal should be a one-stop destination for a business’s APIs — which means it should include not only the APIs themselves but also all the community resources that API users might need. Blogs can be a great way to get the word out about new APIs and to inform users about updates to existing APIs. Forums can create dialogue flows between the API team and the API users, helping ensure that API design choices are informed by user needs.
• Sample Code and SDKs: Developers often work best when they have sample code snippets to help them learn how a new tool or resource works.

[Interested in more tips for managing APIs and driving digital business? See Apigee’s new ebook, “The API Product Mindset.”]