4 Resource scope and hierarchy

As we learned in Chapter 1 (Introduction to APIs), shifting our focus away from actions and towards resources allows us to more easily and more quickly build up our familiarity of an API by leveraging simple patterns. For example, REST provides a set of standard verbs which we can apply to a bunch of resources, meaning that for every resource we learn about, we also pick up 5 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".

4.1      What is resource layout?

4.1.1   Types of relationships

4.1.2   Entity relationship diagrams

4.2      Choosing the right relationship

4.2.1   Do you need a relationship at all?

4.2.2   References or in-lined data

4.2.3   Hierarchy

4.3      Anti-patterns

4.3.1   Resources for everything

4.3.2   Deep hierarchies

4.3.3   In-line everything

4.4      Exercises

4.5      Summary

4.6      References