Clarification on nested resources in included array

1

I have a DB schema that has a few 1-n relationships, lets say a User has many Orders which has many Order Lines:

users ----< orders ---< order_lines

I’ve implemented the include parameter on my APIs so a client can request all of this data in one go like this:

/users/1?include=orders.order_lines

From what a gather from the specs, I understand that I need to put both orders and order_lines in the included section of the API response.

It also seems that they need to appear on the same level, i.e. both orders and order_lines go into the includes array as equals.

My questions are:

  1. Am I understanding this correctly?
  2. If so, why is this represented as a flat structure? Why isn’t order_lines nested inside orders (maybe as another includes?)
2

Yes, I believe you are understanding this correctly. The reason this is done is because each type / id pair should only appear a single time, and the array is simply a bucket to hold the references for the resources and the identifier objects for full linkage. Nothing in the includes section is structurally significant, and all should be the flattened representation of each resource.

I hope that helps!