In a conversation with Thomas Bush at Nordic APIs, Rahul Dighe (Paypal’s API Product and Platform Product Leader) explains his theory on how great API products are built deliberately. This article elaborates on his ideas regarding the deliberate, rigorous process of building APIs with an intentional design for long-term use.
Tip #1: A Thoughtfully Curated Developer Team
Rahul introduces a thought experiment outlining three types of developers who might use PayPal APIs: a newly matriculated freelancer, a payments expert with 10 years of experience in the field, and a distracted developer whose real interest is focused elsewhere. Each type of developer has their own level of experience and set of requirements. With this in mind, Rahul proposes that you “consider the usage patterns of your primary developer archetypes when building new APIs.”
Keeping this consideration in mind, it’s also important to remember that the API is not the end of a product design, rather it is a pathway to the end: the needs will vary from a company looking for a non-API widget for integration, right up to a company looking for a fully fleshed-out API solution.
The last element of this tip is to create a “one-pager.” Rahul advises teams to write up a brief document outlining all of the inputs and outputs, and core integration patterns the API will work to support. This document will serve as a kind of mini-mission statement for the team to refer to throughout the design process.
Tip # 2: Make Naming Your New Obsession
The name of the API will be an anchor the team works around for a long time. Rahul explains that “while you might be able to evolve quickly, there’s no guarantee your developers will too.” Bush refers back to an article he wrote on the same theme, “10+ Best Practices for Naming API Endpoints.”
Tip # 3: Respect Your Own Process
An experienced API designer can push through same-day delivery: “You can whisk through the discovery, design, development, and deployment processes, but you’ll end up with a suboptimal product. Instead, stick to the approach that works, and accept that creating or updating an API will take a little longer than others might like.” To build a strong API, respecting the need for thoughtful progress through the process is essential.
Tip # 4: Build the Complete Ecosystem
An API is just the jumping-off point. It’s just as important to create quality SDKs, a reliable sandbox, and a support staff ready to handle the bugs. These elements elevate the quality of the core API products.
Tip # 5: Stick to Rigorous Standards
An API governance system of internal organizational or communication structures will keep the work a consistent quality. Rahul is guided by Conway’s Law in this thinking.
The best APIs are built with design ground rules rooted in common sense. A uniting governance based on rigorous standards, knowing your target developers well, thoughtful nomenclature, and giving the support assets as much attention as the main product.