How to Create Quality and Customer-Centric APIs

As Head of API Platform at PayPal, Jay Jena focuses on creating a system that is scalable and adaptable to different protocols, made up of APIs that all directly support the company’s business goals.

During my time as the head of API design at PayPal, I had the pleasure of working with Jayadeba Jena (we call him Jay), who joined my team in 2014. Along with the rest of the team, we established API development standards, guidelines, best practices, and experienced first-hand what it means to mature a large-scale API design project.

When I decided to take on a new venture, Jay took the helm of that API design docket, and it’s been fascinating to watch him grow PayPal’s API program to what it is now–a hallmark in the industry.

In our recent podcast, we talked with Jay about ways to create quality APIs and how to inculcate customer-centricity in the process.

1. Define a Business Capability Model

“When we started, we created a business capability model, which comprised all the product capabilities that PayPal offers to its customers.”— Jay Jena.

An important first step when designing APIs is to create a business capability model that outlines all the product capabilities that your organization offers to customers. Think about:

• What does your business mean to its customers?
• Why do customers come to it?
• What do they want to do when they think of your business?

When developing an API, whether internal or external, it’s important to work on it as if it’s going to be externalized. Instead of developing an API solely for your internal or external segment assets, create an API based on your business capability model and the value it offers to end-users.

The advantage of building for potential externalization is that when the opportunity arises to connect with other platforms, namely for new partnerships, there’s little to no rework, and ultimately a faster time to market.

2. Establish the Launch Process

After defining the business capability model, Jay says the next step is to establish the process of taking the API from concept to launch. This process is called the API Product Development Life Cycle (PDLC), and it consists of four stages—define, design, develop, and deploy.

The entry and exit decisions at each phase are driven by an API maturity model, which consists of a set of criteria that stipulates what it means to complete a particular phase.

The “define” phase of the PDLC process involves building a framework that focuses on the importance of customer-centricity in the API design. Work with your product manager to define why you need the API and where the API stands in the overall organization’s product portfolio. Ask the following questions:

• What business value does the API provide?
• How will developers benefit from it?
• What is the target audience?
• What are the security implications of the API?

The product manager can then propose the project, and in collaboration with the domain architect, make a decision as to whether the investment is worthwhile.

Once the investment is approved and the API is designed and developed, you are ready for the final phase—deployment.

3. Practice Consistency

“We have an API tooling blueprint that is standardized. It makes things consistent—whether it’s REST, GraphQL, events-based, or any other type of API.”— Jay Jena.

Jay explains they implement “common components” at PayPal to enforce consistency across their APIs. This involves establishing a set of consistent business entities such that when you capture a construct in your API, you know the specific business entity to use. This practice helps build a solid foundation for any project.

Another way of enforcing consistency is by using tooling to ensure the same styling pattern is applied in a scalable way across all your APIs. Rather than implementing this manually, you can use tooling to automatically apply API standard guidelines, which are a set of objective rules that define how the API should operate. For example, you can use a linter to validate the API and throw errors if anything does not conform to the set rules.

Evangelizing the API with the developer community can also help enforce consistency. This helps showcase the business benefits of the API program in order to get useful feedback on what exists, what doesn’t exist, what it means to you, and what it means to your development. With proper evangelization, you can fuel interest in the API’s offerings and make significant improvements to enhance consumption among the internal and external developer community.

4. Deprecate Cautiously

“We have succeeded in retiring internal APIs. But externally, it’s very costly. So, we design external APIs to live for 10 to 15 years.”— Jay Jena.

Jay has learned to treat depreciation cautiously. While they often retire internal APIs, they do not follow the same approach with external APIs because of PayPal’s unique business model, where its payment integrations are based on trust and security.

If customers are integrated with an API that works and serves their business purposes, making a change is often costly and not desired. So, if new protocols are rolled out, new customers get onboarded to the new APIs. For current customers, they can choose to either continue with the old API or switch to the new one.

Develop with a Customer-Centric Viewpoint

In the end, understanding the customer is critical to developing a successful API. You want customers to work with you because you help them solve problems. And in order to do so, you need proper documentation, a controlled launch process, and a strong push for consistency. Let’s experiences APIs to their fullest!