RESPectful APIs

There is a famous video featuring Bobby McFerrin where he demonstrates the power of the pentatonic scale. To be fair, there are a number of videos that fit the description, but I want to talk about one in particular, in which Bobby McFerrin is on the stage at the World Science Festival. He stands up and starts making small jumps while giving a sound, as if he became an instrument himself, and asks the audience to join in singing the same note. He takes a step to the left and sings a different note. Now silent, he starts jumping left and right, and the audience follows by alternating between the two notes. He then proceeds to do something seemingly unexpected: he jumps to a third position, which was previously unintroduced. The audience, without a hitch, hits the exact right note in unison. Watch the video:

Quite interesting and even cathartic, isn't it? Presumably, this was possible because there is a common wiring in our brains that allows using our shared cultural knowledge and maybe our inherited traits to find that third note without really thinking about it.

So what is a "RESPectful" API and what does it have to do with the pentatonic scale?

RESPectful, spelled this way, is a play on "RESTful" (obviously), and it is a superset of RESTful. This post is intended to highlight a set of good API design practices. In my experience people express joy about working with a particular tool (be it an API or a toaster) when it allows them to reach their goals quickly and without standing in the way.

The RESPectful API respects the time of its users. It is humble and acknowledges that using it is not a goal by itself but a means to an end. The RESPectful API does not require its users to learn completely new concepts unless it's unavoidable. It walks and talks like an average being in the particular ecosystem it exists in.

Drawing the line

Yet, this is more than simply a "when in Rome..." advice. This is also about consciously drawing the line between implementation details and the interface presented to the library user. You might think that hiding implementation details is obvious, but it is more than just declaring private members. It is the GUI analog of not filling half of the screen with heaps of icons that expose various functionality.

Why? Because every bit of complexity exposed to the user will increase the cognitive overhead of using the library and require more time investment from the user. If you remove the casing of a tablet, you have access to all the bits and pieces which you can solder on or remove, given you have sufficient knowledge to do so without breaking the device. Still, 99% of your API users don't want to mess with the internal circuits of your system. They just want to push that one button to take a picture or connect their headphones. And that is the kind of time investment they expect from your API, not soldering on a jack connector. You don't have to make everything tweakable just because you can. Strike a good balance.

Naming things

Correctly naming things is another element of RESPectful API design. A good approach is to imagine the kind of StackOverflow questions your users would ask and use the same wording for naming things in the API. To illustrate this point, let's take a look at the excellent requests library:

• How can I make a GET request? Use the get function. Its return value is the response object.
• How do I get the status code after a response? Read the status_code attribute.
• How do I get the encoding of a response? There is an attribute named encoding.

You get the idea. This, of course, implies that you are aware of the use-cases of your API. This allows making conscious, focused decisions about what to expose to the user, what kind of defaults to use and to choose the right wording.

The third note

The motto of requests is "HTTP for Humans". In other words, it is designed with human thinking in mind, which is illustrated by the language choices and workflows that are presented to the user.

In a sense, this is a kind of UI (a library users' UI). Yes, your API will have a UX regardless of your designing it or not. Go ahead and ask a friend to perform a specific task with your API. If and when they get stuck, take notes. Those are the points of user friction in your API.

Once you know how to make a GET request in requests, you will also know how to make a POST request. Or PUT. Or DELETE. And so on. Why is that? You probably read only the GET example in the docs and your intuition told you "if I change this get to post, I will make a POST request". And your intuition was right.

Bobby McFerrin showed two notes, and the audience knew what the third one was going to be. So design your API like that. Give it a clear, logical structure, have third, fourth, fifth notes that your users can guess without digging through your docs or asking on StackOverflow. That is what makes a good and RESPectful API.