The Design of Web APIs, Second Edition cover
welcome to this free extract from
an online version of the Manning book.
to read more
or

8 Designing user-friendly, interoperable data

 

This chapter covers

  • Designing ready-to-use data
  • Choosing atomic data types and formats
  • Organizing data in objects and arrays
  • Choosing data granularity
  • Designing names
  • Designing consistent and standard data

Imagine a washing machine that shows “EC 50400” when it’s started. You must consult the manual to decode this as the end-of-cycle time in seconds from 00:00. Even knowing this, you must do the math to get meaningful information. A clear message like “Washing ends at 2:35 pm” would be more useful. Although this washing machine fulfills its users’ needs (washing clothes and indicating when it’s done), it is not easy to understand and use: it’s not user-friendly.

Now, imagine that the washing machine uses pictograms for washing programs, like a bucket with two lines underneath for delicate cycles. These pictograms help users select the right program from clothing labels. If your machine lacks them, you can still refer to the meaning of the pictograms on the label for an appropriate setting. I never remember their meaning, so I take a photo of the pictograms with my iPhone, swipe up the photo, and tap “Look up Laundry Care” to get their meanings. Although not always user-friendly, these universal symbols, defined by the ISO 3758 standard, ensure interoperability in the laundry world.

8.1 The user-friendliness and interoperability layer of API design

8.1.1 Overview of the API user experience

8.1.2 Which users’ experiences matter to us?

8.1.3 How API design user-friendliness and interoperability affect UX

8.2 What makes data user-friendly and interoperable?

8.2.1 User-friendly data meets user needs

8.2.2 User-friendly data helps us find and interpret information

8.2.3 User-friendly data limits consumers’ work

8.2.4 User-friendly data is consistent

8.2.5 Interoperable data is consistent and standard

8.3 When and how to design user-friendly, interoperable data

8.3.1 Which data must be user-friendly and interoperable?

8.3.2 When to address user-friendly, interoperable data

8.3.3 How to design user-friendly, interoperable data

8.4 Selecting and crafting ready-to-use data

8.4.1 Choosing simple and meaningful but useful data

8.4.2 Adding supporting data to ease and secure interpretation

Summary