Nobody Wants To Use Your API

When writing an API endpoint or a function, I often find myself being obsessed with it, adding tons of toggles or options so this endpoint handles too many use-cases. In the end, not all of the toggles are used by the client. Even worse, the code is too complex to maintain.

So how do we, as programmers, avoid this pitfall? I think we should apply some product thinking here. First, think of our API as our product. Then, realize that Nobody Wants To Use Your Product. Finally, we write simple APIs that are easy to learn and easy to use.

API is the only product of programming

What is an API, anyway? According to Wikipedia, an API is a "contract" between "the client" and "the server".

Notice that "the client" and "the server" don't need to be talking over a network. So we are defining an API ("a contract") at every level of our application:

  • When writing a function, we are designing an API for the callers of this function.\ What's the name of the function? \ What arguments does this function need? \ What results would this function return?

  • When writing a library, we are designing an API for other programmers.\ What classes/modules does this library have? \ How to use these classes/modules? \ What results can these classes/modules achieve?

  • When writing a RESTful controller action, we are designing an API for the browser.\ What's the path to this action? \ What's the verb to use here? (GET, POST, PUT, DELETE) \ What's the response structure?

  • When writing a page view with HTML, JS, and CSS, we are designing an API for the user.\ What's this form used for? \ What would happen after clicking this button? \ What's the content of this page?

And everything else we do, is to fulfill the API ("the contract") we defined.

  • Write business code\ Fulfill the business logic contract.

  • Write automated tests\ Make sure we fulfill the business contract as specified.

  • Fix various bugs\ The contract was broken, we need to fulfill it again.

  • Improve performance\ Fulfill the performance contract (return the results within x seconds).

  • Document the API\ Explain the contract to the user.

Or we can think it from the opposite. If you as "the server" don't expose an API to "the client", then it doesn't matter how much work you do behind the scenes. Because nobody can use it anyhow.

So API is the most important, if not the only, product of programming.

Nobody wants to use your API

After understanding that API == product in programming, we can start to think from a product perspective. In the article Nobody Wants To Use Your Product, Goran Peuc summarizes this presumption about human nature as:

People are not really into using products. Rather, people are more interested in the end result and in obtaining that result in the quickest, least intrusive and most efficient manner possible.

The same product thinking applies to programming as well. Other programmers are not really into using our API. They may use our API to get some data. Or they may use our API to avoid reinventing the wheel and thus simplify their own code. In a word, they use our API to achieve a result.

KISS (Keep it simple, stupid)1

So what can we do as API designers? If nobody wants to use our API, and people use it only because they want to achieve a result, then we should make our API really simple. And by "simple", I mean easy to learn and easy to use. It's simple to say, but it's hard to do. The ultimate goal requires us to spend tons of efforts: people can spend almost no time to learn our API and start using it. So they can focus on their own concerns, and spend more time figuring out how to succeed in their own way.

Footnotes:

1

Keep It Simple Stupid (KISS) {Principles Wiki}


Rhett Trickett picture

I like this viewpoint of nobody wants to use your 'x'. It's a succinct reminder to keep things as simple as possible for your users.

Someone who I think does this really well is Stripe. They've made it incredibly simple for someone to take payments on their website and have handled all of the devil in the detail. This makes everyone's lives so much easier and that is value people are willing to pay for.

When I was building the first version of Able's editor for posts I had all these required fields to upload thumbnails, set topics, sub-headings and so on. The first bit of uesr feedback I got was that there were too many fields to fill out just to publish an post. So with this latest version of the editor we've stripped it right back to make it as simple as possible to publish.

Yiming Chen picture

Yes, exactly!

And it reminds me of building a MVP. Every time I finish building a MVP, I can always find a feature that's unneeded, or can be added later.

So /nobody wants to use your 'x'/ is also a reminder to not overlook the power of simplicity and the value a simple feature/product can bring to its user.