added chapter4

docs/books/api_design_patterns/part2/chapter4.md

@@ -1,3 +1,82 @@
 # Resource Scope and Hierarchy
 
-Page 47
+## What is a resource layout?
+
+The arrangement of resources in our API, the fields that define those resources, and how those resources relate to one another through those fields.
+
+In other words, resource layout is the entity (resource) relationship model for a particular design of an API.
+
+### Types of Relationships
+
+#### Reference Relationships
+
+The simplest way or two resources to relate to one another is by a simple reference.
+
+<figure>
+    <img src="/books/api_design_patterns/media/chapter4_01.png">
+    <figcaption>A message resource contains a reference to a specific user who authored the message.</figcaption>
+</figure>
+
+- This reference relationship is sometimes referred to as a *foreign key* relationship.
+- As a result, this can also be considered a *many-to-one* relationship.
+    - A user might write many messages, but a message always has one user as the author.
+
+#### Self-Reference Relationships
+
+<figure>
+    <img src="/books/api_design_patterns/media/chapter4_02.png">
+    <figcaption>An employee resource points at other employee resources as managers and assistants.</figcaption>
+</figure>
+
+#### Hierarchical Relationships
+
+- Hierarchical relationships are sort of like one resource having a pointer to another
+    - But that pointer aims upward and implies more than just one resource pointing at another.
+- Hierarchies also tend to reflect *containment* or *ownership* between resources.
+
+<figure>
+    <img src="/books/api_design_patterns/media/chapter4_03.png">
+    <figcaption>ChatRoom resources act as the owner of Message resources through a hierarchical relationship.</figcaption>
+</figure>
+
+In this case, there is an implied hierarchy of `ChatRooms` *containing* or *owning* `Messages`.
+
+## Choosing the Right Relationship
+
+### Do you need a relationship at all?
+
+When building an API, after we've chosen the list of things or resources that matter to us, the next step is to decide how these resources relate to one another.
+
+- Consider a self-reference relationship between `Users`. A single change to one resource can affect millions of other related resources.
+- e.g. if someone famous deletes their Instagram account, millions of records might be to be removed/updated.
+
+Reference relationships should be **purposeful** and **fundamental** to the desired behaviour. Any reference relationship should be something important for the API to accomplish its primary goal.
+
+### References or in-line data
+
+- Where data is in-lined, we only need a single API call to retrieve all the relevant information.
+- But what if we aren't interested in that information very often?
+    - Then our response is bloated.
+
+Optimise for the common case - without compromising the feasibility of the advanced case.
+
+### Hierarchy
+
+The biggest differences with this type of relationship are the **cascading** effect of actions and the inheritance of behaviours and properties from parent to child.
+
+- Deleting a parent resource typically implies deleting a child resource.
+- Access to a parent generically implies the same level of access to the children resources.
+
+## Anti-patterns
+
+### Resources for Everything
+
+It can often be tempting to create resources for even the tiniest concept you might want to model.
+
+**Rule of thumb**: If you don't need to interact with one of your resources independent of a resource it's associated with, then it can probably be a data type.
+
+### Deep Hierarchies
+
+Overly deep hierarchies can be confusing and difficult to manage.
+
+Page 63 4.3.3 in-line everything