5 Designing a straightforward API

Now that you have learned to design APIs that actually let consumers achieve their goals, you have a solid foundation in API design. Unfortunately, only relying on the basics does not mean that consumers will actually be able to use the “APIs that do the job.” Remember the UDRC 1138 shown in figure 5.1? It is possible to design a terrible interface that does the job.

When faced with an unfamiliar everyday object, what do you do? You observe it. You analyze its form, labels, icons, buttons, or other controls in order to get an understanding of its purpose, its current status, and how to operate it. To achieve your goal using this object, you might need to chain various interactions, providing inputs and receiving feedback. When you do all that, you don’t want uncertainties; everything must be crystal-clear. You don’t want to waste time, so everything must go swiftly and efficiently. You want your experience using any everyday object to be as straightforward as possible. You definitely don’t want to face another interface like the UDRC 1138. That is the basis of usability. And it’s exactly the same with APIs.

5.1 Designing straightforward representations

5.1.1 Choosing crystal-clear names

5.1.2 Choosing easy-to-use data types and formats

5.1.3 Choosing ready-to-use data

5.2 Designing straightforward interactions

5.2.1 Requesting straightforward inputs

5.2.2 Identifying all possible error feedbacks

5.2.3 Returning informative error feedback

5.2.4 Returning exhaustive error feedback

5.2.5 Returning informative success feedback

5.3 Designing straightforward flows

5.3.1 Building a straightforward goal chain

5.3.2 Preventing errors

5.3.3 Aggregating goals

5.3.4 Designing stateless flows

Summary