“Great API products don’t get built by mistake,” says Rahul Dighe, the API and Platform Product Leader at PayPal. Even if you take into account all the trending principles of API ownership — design-first, API-as-a-Product, governance, KPIs, and more — you still might end up with an API that’s difficult to use. So, what advice would an API product strategist with over ten years of experience give?

In this post, we’ll look at key pointers from Rahul Dighe’s talk at the 2019 Platform Summit. These five insights should help you to create developer-friendly APIs that will stand the test of time.

1. Know Your Developers

It should come as no surprise that building developer-friendly API products start with knowing your developers. As a thought experiment, Rahul introduces three developer archetypes who might use PayPal’s APIs. They include a freelancer who is fresh out of college; a payments expert, who has been in the payment space for the last ten years; and an uninterested developer whose true interests lie elsewhere.

When you look at these archetypes, you’ll see that developers all have different levels of investment and experience. Not to mention, they each have their own set of requirements, which dictates how they interact with the APIs.

As a result, Rahul suggests you consider the usage patterns of your primary developer archetypes when building new APIs. After all, APIs are a means to an end and not the end itself. Some partners might just need a single, non-API widget for their integration, while others will be looking for a full API solution to migrate to from another provider.

A particularly actionable piece of advice Rahul gives is to write a “one-pager,” which contains all of the inputs and outputs and core integration patterns you hope to support with your API. This document will act as a quick reference point during the API design process, allowing you to ensure that what you’re building will provide the best experience to your developer audience.

2. Be Obsessive about Naming

Rahul’s next piece of advice was the inspiration for my recent article, 10+ Best Practices for Naming API Endpoints. He says you should be “obsessive” about how you name your APIs. After all, once you name an API, it stays there for a pretty long time. And while you might be able to evolve quickly, there’s no guarantee your developers will too.

If you want more specifics on how to do naming right, be sure to check out the article linked above. If you’re just wondering why naming matters, the answer is simple: it might not sound like much. Still, the effect of redundant, inconsistent, or non-descriptive names can quickly add up, making your APIs challenging to consume.

3. Always Stick to Your Process

By this point, many big enterprises have a tried-and-tested process for building new APIs, that incorporates plenty of time and due diligence. It starts with a discovery phase, where you lay out the problem you intend to solve, which is followed by a design phase, where you begin to think about concrete endpoints, fields, security features, tools, specifications, and user stories. Then, you enter a development phase, before finally launching your new API.

This process usually results in intuitive and all-round great APIs. However, Rahul recalls getting into a discussion with a corporate leadership team, concerning why it took an entire month to add one field to an API. It’s easy to be swayed by external pressures like this, but Rahul strongly believes you should stick with your guns.

As an API designer, Rahul says you’re forced to build something that’s needed today, but will still be used five or six years in the future. 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.

4. Build a Complete Ecosystem

While getting a single API out can be a challenge in and of itself in some business environments, Rahul says that APIs are just the start, and that you can’t forget about the rest of the ecosystem. In particular, he highlights the importance of SDKs, a reliable sandbox, and debug-ready support staff.

Rahul believes that these little things do matter. Sure, it takes time to put all the pieces in place, but these supporting ecosystem assets significantly contribute to the usability of your core API products. Importantly, you do genuinely have to care about and maintain these assets: if you’re not careful, you’ll end up with old, unhelpful documentation, and a box ticked somewhere on the API-as-a-Product checklist.

5. Think API Governance

Rahul’s last piece of advice is to think about how you organize and govern your suite of APIs. He draws attention to Conway’s Law, which suggests that we build systems that reflect our internal organizational or communication structures. The traditional approach to combating this — i.e. building consistent APIs, despite having different teams work on them — is to use some kind of API governance system. In theory, by subjecting all API product teams to the same standards, the APIs should feel consistent.

In practice, Rahul believes that there will always be little nuances between APIs built by different teams, which adds complexity for developers who are integrating two or more of them. To combat this, Rahul suggests using something along the lines of the Inverse Conway Maneuver (explained in the article above): if you’re always going to have two related API products, have a single team be responsible for both developer interfaces. That way, the APIs are bound to be consistent.

Final Thoughts

The best API products are built when you do things properly. That starts with knowing who your target developers are and how they’ll use your API. Later, it means sticking to unnegotiable, tried and tested processes and organization-wide governance standards, and getting names right the first time around. Finally, there’s more to an API ecosystem than just the API itself, and maintaining supporting assets like docs, SDKs, and sandboxes is crucial.