As we learned in chapter 1, shifting our focus away from actions and toward resources allows us to more easily and more quickly build our familiarity of an API by leveraging simple patterns. For example, REST provides a set of standard verbs we can apply to a bunch of resources, meaning that for every resource we learn about, we also pick up five different actions that can be performed on that resource (create, get, list, delete, and update).
While this is valuable, it means that it becomes far more important to think carefully about the resources we define as part of an API. A key part of choosing the right resources is understanding how they’ll fit together in the future. In this chapter, we’ll explore how we might lay out the various resources in an API, the options available, and general guidelines for choosing the right way to associate resources with one another. Additionally, we’ll look at a couple of anti-patterns (things not to do) when considering how to lay out a set of resources in an API. Let’s start at the beginning by looking at what we mean specifically by resource layout.