It’s no secret that the pandemic significantly amplified the need for organizations to embrace a digital-first strategy. Digital transformations that had been deprioritized in favor of other organizational goals shifted front and center overnight, with unprecedented urgency. According to a 2020 McKinsey Global Survey of executives, companies accelerated the rate at which they digitized internal operations and expanded digital-product portfolios by several years, despite the significant challenges posed by COVID-19.

At the heart of these digital transformations is integration, facilitated by application programming interfaces (APIs). Once thought of simply as “messengers” or “intermediaries” that transmitted data between software systems, APIs are now recognized as the “connective tissue” of digital ecosystems, offering limitless integration and business opportunities to the organizations that build and leverage them. Because of the unique potential APIs represent, product managers overseeing their development must adopt an approach that unlocks their latent value, one that emphasizes flexibility and extensibility to ensure flawless integration experiences.

Doing More With Less

Even before the past unprecedented year, the value of APIs to organizations had been well documented, and the API economy had been thriving for some time. To understand today’s integrations landscape, it is helpful to explore the origins of the Best of Breed (BoB) philosophy. Before the 1990s, software vendors marketed enterprise resource planning (ERP) suite solutions that attempted to solve a wide variety of organizational challenges. Increasingly, these suites came to be viewed as cumbersome and impractical, because they failed to address organization-specific use cases. As a result, vendors began building more focused tools that solved challenges for one functional area, instead of larger suites that attempted to do everything for everyone. Enterprises welcomed the idea of choosing from a variety of smaller, more specialized tools and began assembling collections of individual solutions that best matched their particular needs.

Connecting the Dots

As the BoB approach gained steam, integrations became a crucial part of product strategies. A tool that was great at solving problems for one area of a business had to be able to integrate well with other BoB products that were likely to be used alongside it. Consider HubSpot, the sales and CRM software implemented by organizations to track and optimize their sales pipelines and customer relationships. Hubspot readily integrates with other BoB software like DocuSign (digital signatures), Twilio (email/SMS notifications), and Zendesk (customer support) without requiring additional development from the customer’s engineering teams.

The need for complementary tools to seamlessly plug into one another was accompanied by an industry-wide shift toward embracing openness rather than limiting interactions between systems. Somewhere along the way, the number of integrations a product supported became a metric worth marketing.

The Platform Proposition

The true value of API for product managers, however, goes beyond their ability to coordinate disparate tools and systems. At their best, APIs are the collective mechanism for turning products into platforms. This is where platform product management plays a crucial role. Products, by definition, are tools that have a specific application; hence “apps.” They are limited in their ability to create multiple value propositions and, by extension, multiple revenue streams. Platforms, on the other hand, add value in a different way: by providing the infrastructure layer upon which numerous products can be built, and enabling a more comprehensive approach to product management.

APIs open new business channels by capitalizing on the expertise of the third parties who leverage them. Consuming developers can design a real estate app that uses Google Maps’ Places APIs to help users house hunt, or they can leverage Skyscanner’s Flight APIs and Expedia’s Hotel APIs to create an ecotourism site that specializes in travel to a specific location. These developers and external partners benefit by gaining access to existing data and services they can adapt for their businesses, and API owners like Expedia expand their reach and monetize opportunities that would not exist had they continued to, say, only list hotels on their product.

Making It Modular

A successful API product development strategy requires a mindset shift from product thinking to platform thinking. This means building products in a modular, open-ended fashion that allows their functionality to be recombined and that prioritizes flexibility for consuming developers. Think of IKEA shelving systems, which customers can purchase, assemble, and customize in different ways to meet a variety of needs. Good API product managers see APIs for what they are: tools for scaling the business and developing valuable partnerships. Recognizing this potential means implementing best practices to ensure adoption.

Delighting the Developers

If there’s one foundational pillar of a solid API strategy, it’s developer experience (DX). For API integrations, the “customers” product managers need to delight are consuming developers. These are the users who ultimately call/integrate with an API, the potential partners who can help realize a product-to-platform vision. Labeling their experience “DX” instead of “UX” acknowledges that they are not typical end users—they are significantly more technically adept. In order to empathize with them, it is essential to understand their specific needs and expectations.

Best Practices

The following, though by no means representing an exhaustive list, are essential practices for building first-rate APIs that ensure friction-free and consistent, predictable integration experiences for consuming developers. Embracing the concept of API as a product is crucial, as it grants APIs the same attention given to any other product. Product managers should approach designing APIs in a scalable manner, defining a best-practices framework and publishing it as a document that teams can refer to when building new APIs.

Consistent naming conventions and endpoints

Establishing consistent naming conventions for API endpoints that clearly identify the nature and purpose of the API removes ambiguity and contributes to a positive and predictable DX. It is best to choose a common base URL for all APIs and a framework for the trailing URL that avoids jargon and abbreviations. Nordic APIs offers a helpful list of tips for naming endpoints.

Detailed success and failure response structures

Developers want and expect familiar data objects and status codes for success and failure responses. That means a 2xx status code for success scenarios, a 4xx code for client-side failures, and a 5xx code for server-side errors. However, specificity is key. A call to a “send email” API that simply returns a 4xx response without additional information makes for a poor developer experience, because it merely confirms that the error was in the client request without giving additional information as to what exactly went wrong.

{
   "status": 400,
   "message": "incorrect request"
}

In contrast, a response that offers specific details in human-readable format and in the form of a unique error code can help developers quickly decide how to rectify the error scenario, write code to address the issue, and retry the API call.

{
   "status": 400,
   "message": "To recipient not specified",
   "code": 21221
}

For optimal DX, response structures and the keys that communicate status should be consistent across APIs. For example, the error code field in the above should invariably be referred to as “code” in every API, not “code” in some APIs and “errorCode” in others.

Configurable rate limits

Rate limits govern how accessible an API is by determining how many times a user can call it in a single unit of time. Rate limits that are too high can flood systems with an unmanageable number of requests that degrade performance, while unreasonably low rate limits can cause pending transactions to queue up in users’ systems. Both contribute to poor DX. When designing APIs, it is best to allow for rate limits that can be adjusted based on specific business cases and circumstances. High-volume customers, for example, may have a genuine need to call APIs more frequently.

To best determine appropriate rate limits, it is helpful to first group APIs into meaningful categories according to the frequency and volume with which they are called. For example, APIs that configure primary customer data (profile/account creation) are called less frequently and can handle lower rate limits, while transaction APIs (“create order,” “send email”) are called more frequently, requiring higher rate limits. Establishing categories, or tiers, for different use cases makes for more reliable and scalable APIs. For an example of clearly defined rate limits, see Slack’s API documentation.

Comprehensive documentation

Documentation serves as the user manual for an API. It clearly articulates to developers what an API does, how to use it, and what to expect from it. Good documentation is written in clear, accessible language, is detailed and interactive, and offers plenty of demos and code snippets to make integration simpler. In this way, it facilitates easy onboarding and a speedy Time to First Hello World (TTFHW), an important metric that represents how swiftly a developer can successfully call their first API.

Documentation should clearly identify which fields in the API request are mandatory and which are optional, as well as the minimum and maximum length and data type for those fields. Essentially, it should include everything necessary to set expectations and remove obstacles for consuming developers. Developers creating database schemas in their systems, for example, should not have to later adjust the length of columns in tables because the documentation did not specify the parameters.

API documentation can increase adoption not only by serving as a reliable reference for consuming developers but also by acting as a marketing tool for the API itself. Often, the first person to encounter API documentation is a business-facing stakeholder, who browses it during the initial phases of product evaluation. It should therefore not only include details about the API’s technical elements but should also clearly articulate the business use cases the API makes possible.

There are a number of tools on the market that can assist with generating comprehensive API documentation. Reviewing examples of high-quality documentation, like Stripe’s, is also helpful.

Bringing It All Together

Integrations represent a vast domain with many components, but understanding the core principles of a good API is fundamental to developing a solid strategy. APIs are much, much more than mere system connectors. They are the building blocks of expansive digital networks and the keys to opening up new revenue streams and releasing untapped value. Because of this, a successful product management API strategy isn’t just about building products; it’s about building potential. An API product manager must adopt a platform mindset and prioritize the factors that will smooth adoption for the potential partners who can then take their API, integrate, and run with it.