8 Designing user-friendly data
This chapter covers
- Choosing and designing ready-to-use data
- Choosing atomic data types and formats
- Organizing data in objects and arrays and choosing granularity
- Designing names
- Designing consistent and interoperable data
Imagine a washing machine indicating "EC 39660" once started. Users must read the instruction manual to understand that the end of cycle time is represented by the number of seconds since 00:00. Still, even when knowing that, they must do some math to get meaningful information. While the washing machine fulfills users' needs (washing clothes and indicating when it’s done), this information makes it not easy to understand and use: it’s not user-friendly. An explicit message such as "Washing ends at 11:01 am" would be more helpful.
The same goes for APIs. Unhelpful data, such as {"ec": 39660}, can make developers' work more complicated than it should be, resulting in many questions, complex code, risks of errors and imprecision, and lengthy development. Fulfilling needs is a good start, but it’s only the first layer of API design (see section 1.6.2); we must also ensure data and any other aspect of our APIs are user-friendly. It helps create straightforward APIs that developers can use intuitively and even love.