Developers are users too — Introduction

Usability — learning from the UI, applying in API

When talking about usability, we tend to think of user interfaces, may it be a maps, messaging or photo sharing app. We want our user interfaces to have several qualities, for example a maps application should be:

  • Intuitive — to be able to easily know how to navigate from A to B.
  • Efficient — to get the navigation directions quickly.
  • Correct — to get the right path from A to B, without any roadblocks or other impediments.
  • Provide appropriate functionality — be able to explore the map, zoom in, zoom out and navigate.
  • Provide appropriate access to the functionality — be able to zoom out, by just pinching the map.

We should expect the same qualities from the APIs we work with too. If the UI is the interface between users and functionality, then the API is the interface between the developer using it and the body of code that implements that functionality. APIs, like UIs, need to be usable as well.

Libraries, frameworks, SDKs — APIs are everywhere! Whenever you’re separating code into modules, the classes and methods exposed by the module become the API. It’s what other developers (and ‘future you’!) need to work with.

Usability can be measured to be the inverse of the amount of time needed to understand how to use something. Both beginner and expert developers spend a lot of time learning how to work with new APIs. A low degree of usability leads to incorrect usage of APIs, which can result in bugs and even security problems. These issues end up affecting not only the developers integrating those APIs, but also the users of those applications. That’s why it’s critical to provide a usable API.

Nielsen and Molich created a well known set of UI usability heuristics that can be easily applied to any product, including APIs, and can be combined with Bloch’s guidelines for designing a good API.

  1. Visibility of system status
  2. Match between system and the real world
  3. User control and freedom
  4. Consistency and standards
  5. Error prevention
  6. Recognition rather than recall
  7. Flexibility and efficiency of use
  8. Aesthetic and minimalist design
  9. Help users recognize, diagnose and recover from errors
  10. Help and documentation

In the next articles, we’ll take a look in depth at each of these principles and examine how they might be applied to API design. Stay tuned!