6 Designing a predictable API

This chapter covers

Being consistent to create intuitive APIs
Adding features to simplify use and adapt to users
Adding metadata and metagoals to guide users

In the previous chapter, we started our journey to learn how to build usable APIs and discovered fundamental principles we can use to create straightforward APIs that are easy to understand and easy to use. This is good—we now know how to design a decent API. But we can do better. What about designing an awesome API? What about designing an API that users will be able to use instinctively without thinking about it, even if it is the very first time they’re using it? How can we do that?

6.1 Being consistent

6.1.1 Designing consistent data

6.1.2 Designing consistent goals

6.1.3 The four levels of consistency

6.1.4 Copying others: Following common practices and meeting standards

6.1.5 Being consistent is hard and must be done wisely

6.2 Being adaptable

6.2.1 Providing and accepting different formats

6.2.2 Internationalizing and localizing

6.2.3 Filtering, paginating, and sorting

6.3 Being discoverable

6.3.1 Providing metadata

6.3.2 Creating hypermedia APIs

6.3.3 Taking advantage of the HTTP protocol

Summary