Something my ninth-grade English teacher said has had a lasting impact on the way I think about API usability and design. Explaining how to write readable copy, he advised, "Always assume that your reader is lazy, stupid and mean." Harsh, I know, but his message meant that we should write with empathy for readers. The best way to do that is to write with the most difficult and critical reader in mind.
As a software engineer, I've applied this advice often to improve product usability. Whether developing user interfaces, back-end architecture or applications, designing with the most difficult user in mind is a great way to ensure that my final product is clear and intuitive. In this tip, I describe how I have applied this approach to designing for API usability to reduce latency, complexity and programming overhead.
In eliciting requirements, I find there can be a disconnect between the information that is in my head and the information in users' minds. That's why it is easy to make false assumptions about the intuitiveness of your API design. By assuming that my user is lazy, stupid and mean, you can ensure that I am not going with my assumptions and always designing with the user in mind.
The lazy user
In a nutshell, writing articles or designing APIs for a lazy person means to avoid filler. Don't write 10 pages when you can get your point across clearly in two. Nobody likes having their time wasted, and jamming a paper full of useless information will do exactly that. Putting this principle to work in designing for API usability requires finding a proper balance. While it can be tempting to return every piece of information about an object, it's important to be aware of the difference between necessary information and supplemental information.
The more information you cram into a response, the longer the queries will take and the slower your API will be. On the flip side, too little information will require your consumers to make additional API calls, which will slow down and complicate their integration. Finding a balance between the information a user needs and the information not needed is crucial to improving API usability and reducing latency.
The stupid user
Treating your readers like they are stupid doesn't mean talking down to them. It simply means not using big words for the sake of using big words. Connecting to your readers through a commonly understood dialect improves readability. Viewed through the lens of API design, this means trying not to get too clever. For example, don't use a proprietary authentication scheme for your API if a well-documented standard like OAuth is sufficient.
Maintaining simplicity in your API design is key to ensuring a positive reception from developers implementing it. As engineers, we have a tendency to "over-engineer" solutions to problems, but a fancy solution can be your undoing if it only serves to confuse your consumers and make their lives more difficult. Use accepted development standards and implementations whenever possible, and always be aware of the objective complexity of any solution.
When the user is mean
A mean reader is someone who interprets everything you write the wrong way. So, avoiding ambiguity is crucial to ensuring the point you get across is the point you're trying to get across. This is why it is important to take some time to ensure that what you are writing (or building, in the case of API design) is clear and concise.
This means that everything from your endpoints to your documentation should be clearly defined. There is nothing more frustrating than having to reverse engineer an API because the documentation and schema were unclear or nonexistent. Every endpoint, action and response should be intuitively defined and documented (with examples if possible). APIs are meant to reduce development overhead for your users by allowing them to add new functionality to their own projects without having to build it in-house. If your API doesn't facilitate this need, then it is time to rethink your approach.
Pleasing the difficult user
Designing APIs for usability can be tough. More than just programming, fostering API usability means empathizing with your users to create a clear and intuitive interface for them. As a major advocate of documentation-first API design, I understand how important it can be to get the design right early on. By designing with the most difficult user in mind, you can ensure that your consumers will have a positive experience with your API from day one.
Zachary Flower is a freelance software engineer based in Boulder, CO. He is currently senior developer for PivotDesk and a contributing writer for Fixate IO and TechTarget.
What surprises does REST hold for developers in the future?
Learn the basics to building an API interface
How to choose an API design that complements a hybrid cloud