2 Designing an API for its users

This chapter covers

  • Which perspective to focus on when designing APIs
  • Approaching API design like designing a user interface
  • How to accurately determine an API’s real goals

If you were eager to jump right into the programming interface design battlefield, I’m deeply sorry, but you will have to wait for the next chapter. In this chapter, we look at the API’s users’ needs.

When you want to build or create something, you need a plan. You need to determine what you want to do before actually doing it. API design is no exception.

An API is not made to blindly expose data and capabilities. An API, like any everyday user interface, is made for its users in order to help them achieve their goals. For a social networking API, some of these goals could be to share a photo, to add a friend, or to list friends. These goals form the functional blueprint required to design an effective API, and that’s why identifying goals is a crucial step in the API design process. These goals—what users can achieve using your API—must make sense for the users, and none should be missed.

2.1 The right perspective for designing everyday user interfaces

2.1.1 Focusing on how things work leads to complicated interfaces

2.1.2 Focusing on what users can do leads to simple interfaces

2.2 Designing software’s interfaces

2.2.1 Viewing an API as software’s control panel

2.2.2 Focusing on the consumer’s perspective to create simple APIs

2.3 Identifying an API’s goals

2.3.1 Identifying the whats and the hows

2.3.2 Identifying inputs and outputs

2.3.3 Identifying missing goals

2.3.4 Identifying all users

2.3.5 Using the API goals canvas

2.4 Avoiding the provider’s perspective when designing APIs

2.4.1 Avoiding data influences

2.4.2 Avoiding code and business logic influences

2.4.3 Avoiding software architecture influences

2.4.4 Avoiding human organization influences

2.4.5 Detecting the provider’s perspective in the API goals canvas