API Management Best Practices | Toptal®

As more information is shared across systems, application programming interfaces (APIs) have become strategically critical for organizations of all types and sizes. The number of public APIs available increased from fewer than 400 in 2006 to more than 20,000 in 2019, according to a 2021 Deloitte report. A 2022 report by Rapid found that 75% of developers utilize internal APIs and nearly 54% work with third-party APIs. The report also found that the number of APIs an organization maintains grows with the size of the organization: 32% of companies with 201 to 1,000 employees use between 11 and 50 APIs, whereas almost 38% of companies with more than 10,000 employees use more than 250.

Managing even a single API is a complex task, involving multiple stakeholders from many technology and business functions. If things go wrong, the losses can be significant. This is why it’s important to have a strategic and holistic approach to managing APIs. One way of achieving this is to treat the API as a product, a concept known as AaaP. To help you navigate the API landscape, I’ve gathered these top API management best practices from my decade working as a digital product specialist.

API Types: An Overview

Simply put, an API is a set of rules and protocols that allows different systems to communicate and share data and capabilities. APIs are used by different systems and applications, so the end customers are developers, architects, product managers, and other professionals managing these systems and applications. There are many types of APIs and multiple ways to organize them. When developing and managing an API, consider the category (or categories) it falls into. Here are three of the most common.

1. Access: Internal, Partner, and Public

As the name suggests, internal APIs are used within an organization and are not available to any outside systems. They are more common in larger organizations, where they are used to boost productivity, share capabilities, and improve processes. These large-scale APIs are the most challenging to work on, but they also offer exciting prospects for businesses and products.

Partner APIs are available to select parties that must register in order to use them. They are a great way for companies to share certain data or capabilities while retaining access control, setting requirements for use, and reserving the ability to revoke permissions at any time. One of the most well-known examples is the Amazon Selling Partner API—a mature, successful API used by thousands of vendors that offers a catalog of processing functionalities for orders, payments, shipping, and reporting.

Public APIs are open to everyone, although they usually require registration to obtain the API keys. These APIs can stimulate innovation and build ecosystems, and are often viewed as a public good, offering easily accessible infrastructure. An example is the NASA API portal, which provides public access to data such as moon, Earth, and Mars imagery and the Near-Earth Object Web Service. IMDb, Yahoo Finance, Shazam, and Google Maps all have public APIs too.

2. Target User Group

These APIs are classified by the commercial entities they support: business-to-business (B2B), business-to-business-to-consumer (B2B2C), government-to-business (G2B), government-to-business-to-consumer (G2B2C), government-to-consumer (G2C), and many more. The Amazon Selling Partner API would fall under the B2B2C group, as it is used by businesses with consumers as end users. The NASA APIs are G2B or G2C, as they are provided by a US government agency.

3. Technology

As APIs exchange data and commands, they require clear architectures and protocols. There are different types of APIs based on the technology used to build the API, such as REST (representational state transfer), RPC (remote procedure call), and SOAP (simple object access protocol).

REST, commonly known as RESTful, is the most widely employed architectural style for designing networked applications. It is based on a set of principles that promote scalability, simplicity, and interoperability. REST APIs are mainly used for building web services and are language-agnostic, enabling different clients to interact with the same API. They provide a flexible approach to building distributed systems, using unique uniform resource identifiers and providing access through standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE.

Managing APIs As Products

There is no single way to divide or list the key aspects of managing an API as many of them intertwine or overlap, but here I break down the various elements to help you apply a product development approach to managing APIs.

API Product Strategy

Product strategy for APIs is similar to digital product strategy. It is two-sided, covering both the “why” and the “how.” The why is the need or problem you are solving—the ultimate goal for the API. The how is focused on the technical execution—how you’ll solve the problem.

As with any product, it’s important for the API product strategy to be aligned with your organization’s overall strategy and business model. With a fitness app, for example, a strategic goal would be to increase both the number of users and user retention rates. One of the ways to support this would be to connect to a user’s health data so that their experience becomes seamless. To do this, you might use Apple HealthKit and Android Health Connect.

For some companies, the API is the core of the business. Take the example of Stripe, a payment services provider that lets merchants accept debit cards, credit cards, and other payments. In this instance, company strategy is the de facto API strategy, and success or failure of the API is directly related to the business overall.

Other organizations may have a business model that the API will directly support. A good example would be a traditional bank offering a partner API to support open banking initiatives. Open banking enables consumers and SMBs to share their bank and credit card transaction data securely with trusted third parties that provide them with applications, features, and services to save time and money.

Whether the API is the core of the business, as with Stripe, or a supporting pillar, such as open banking enablement, strategy alignment is crucial.

API Design and Developer Experience

Design is the process of deciding how something will work, look, and be used. Building an API requires making decisions about the interface, which will have implications for user interaction, safety, and other factors. A good design supports the strategy, improving ease of integration, security, and scalability in order to acquire more users.

When it comes to designing APIs, user experience (UX) is referred to as developer experience (DX). The average developer will have certain expectations and requirements for an API, including simplicity and ease of use, clear and comprehensive documentation, consistency, error-handling and debugging support, and reliable performance. These should all inform the API design.

A good way to improve DX is by setting up a developer portal where all the resources for an API are readily available and neatly organized. Examples of such portals include PayPal Developer, Spotify for Developers, Stripe Developer tools, and Twilio Docs. Additionally, developers value community and support, so features such as a community-driven roadmap, developer advocates, feedback channels, and forums can be beneficial.

API Robustness and Security

Robustness and security are generally part of API design and are equally important. Robustness refers to the ability of an API to handle unexpected situations and errors—ensuring an API can withstand high volumes of requests, recover from failures, and handle various data formats. If an API is not robust, it may become unresponsive under a heavy load, resulting in downtime or degraded performance for applications relying on it. This can have severe consequences for both the application (loss of users) and the API provider (service-level agreement breach and resulting damages).

Security is about protecting the API and the data it processes from breaches, unauthorized access, and malicious attacks. If an API is not secure, the consequences can be similar to those above, with the additional risk of steep fines for data breaches.

API Development, Testing, and Deployment

Development, testing, and deployment are crucial steps in making an API available to users and ensuring its quality, functionality, and successful integration. During the development phase, the team designs and implements the API by creating the necessary endpoints, defining data structures, establishing expected behavior, and so on. Testing is needed to validate performance and compatibility. Unit, integration, and end-to-end tests (among others) are conducted to evaluate the API’s behavior in real-world scenarios.

Once development and testing are finished, the API is deployed to a production environment. This involves configuration and ensuring that the proper infrastructure and security measures are in place. Continuous integration and deployment practices are often used to streamline this process.

API Discovery, Evaluation, and Integration

On the consumer side, discovery, evaluation, and integration are the main steps in connecting to and utilizing an API. Just as you would as a product manager, as an API product manager, you should walk in your customer’s shoes, considering these different stages, and thinking about how you can meet customer needs in the best possible way. How can customers discover your API? How can they learn more and participate in evaluating it? How is the integration process designed? These considerations tie into DX, design, and strategy.

API Governance and Continuous Development

API governance refers to the set of processes, policies, and controls implemented to ensure effective management, usage, and compliance. An API is a live, continuously evolving system, which means it is never fully finished. As new customers use the API, different use cases may arise, and new features will be added. To observe and manage this, good governance is vital. In their book Continuous API Management, authors Mehdi Medjaoui et al., describe three examples together with real-life use cases of governance patterns:

• Design authority: PayPal’s central design team validates all new API designs.
• Embedded centralized experts: HSBC has a network of API champions to support local project teams.
• Influenced self-governance: Spotify applies an approach called Golden Path, providing a catalog of recommended tools and services to engineering teams that have been endorsed by the design authority.

API Metrics

Metrics are essential for managing and measuring the success of an API, as they provide insights into performance, usage, and health. The main success factors for an API reflect what matters to the end customers. In her book API Analytics for Product Managers, Deepa Goyal, product strategy lead at Postman and former head of API experience at PayPal, divides API metrics into three categories:

1. Infrastructure metrics, which cover product performance, usage, and reliability
2. Business metrics, which cover revenue, adoption, and operations
3. Product metrics, which span several different stages, including discovery, engagement, acquisition, activation, retention, and experience

Goyal also provides examples of these metrics, as shown in the table below:

This is just one way to categorize API metrics; how you choose to track and utilize metrics will depend on your business context. There’s a big difference between commercial APIs such as Stripe, where high importance will be given to things like adoption metrics, market share, and earnings per user, and internal APIs, where the goal is not to conquer a market but to share capabilities or improve processes.

Think of the API As a Product

As APIs become increasingly prevalent and important to business operations, you must implement a strong API management solution. Managing an API as a product means always keeping the end user in mind and ensuring alignment with organizational goals. It means thinking about DX, governance, robustness, security, testing, and deployment. It also means measuring API success using relevant metrics.

If you haven’t yet created an API in your organization, treat the framework above as a blueprint for development and implementation. If you already have an API, or several APIs, consider using these best practices to strengthen and improve quality and performance. While you may not have previously thought of an API as a product, adopting this perspective can give you greater control and improved insights, allowing you to utilize product management expertise so that each API better serves your business.