Non-technical API Design

Originally published on August 27, 2019, on my personal blog.

Last week I published a tweet asking people that consider themselves API Designers what their job consists of. It’s interesting to see that I’ve got a bunch of answers but not the ones I was looking for. The thing to note is that most people who believe they work in API Design are actually working on technical API definition, not on designing the API from the ground up. Their job primarily consists of making sure that the API is well defined and documented from a technical point of view. They measure their success by how easy developers understand and start using the APIs that they’re defining.

Don’t get me wrong—the jobs of these people are very important and necessary in the world we live in. However, these are not the most important jobs when it comes to launching API Programs. In my opinion, the most important activity is making sure that whatever the API is providing is fully aligned with how users expect the application to behave and about their own experience. For this reason, I believe that Product Managers should be involved in API Design from the first day. The tools that enable that participation don’t exist and that makes things more exclusive to the technical world where people that navigate the Product Management sphere don’t like to operate that much.

Why aren’t companies building API Design tools that make it easier for non-technical people to collaborate in the API Design activities? A valid reason would be that there’s no market for non-technical API Design tools. Another reason is that there’s a market but it’s not large enough to dedicate the creation of fully blown products. After all, companies exist to make money selling their products. So, what about Open Source tools? Why aren’t there good Open Source tools that help you design your APIs from a Product Management point of view? That is a very good question and one that deserves some reflection and investigation, in my opinion.

For one, most Open Source tools are built out of the need of their creators. If most Open Source contributors are themselves engineers and developers, why would they build a tool where the target user is not like themselves? That’s a good answer but not very satisfying. Perhaps Product Managers don’t believe that it’s their place to participate in the design of APIs and they delegate that task to engineers. It’s natural to think that if the API Design area is mostly targeted at engineers, then the engineers themselves should be the ones participating in the process.

The question that seems to be bubbling to the surface is quite interesting. It looks like Product Managers don’t believe that APIs should be designed with the end-user in mind. Instead, they believe that only engineers would benefit from a good API Design.