Nested objects in REST

Question

I have simple set of resources, not more than 10 types, with some one-to-many relationships. For example

• An order has many entries
• An entry has many comments
• A machine can have multiple entries associated
• A material can have multiple orders associated

All the model objects are identified by a unique Primary Key

I communicate using REST HTTP calls. How should the objects be modeled?

Option 1: Nesting objects

The relationships can result in nested objects:

entry{
  PK: '_',
  prop1: '_',
  prop2: '_',
  machine:{
    PK: '_',
    prop3: '_'
  },
  order: {
    PK: '_',
    material: {
      PK: '_',
      prop4: '_'
    }
  }
}

And similarly for the other objects

Option 2: Reference by PK

This approach "flattens" the objects:

entry{
  PK: '_',
  prop1: '_',
  prop2: '_',
  machinePK: '_',
  orderPK: '_'
}

What is the best approach? obviously both have clear advantages and disadvantages. Is an hybrid approach a viable solution? If so, which criteria should I follow to chose between "flat" or "nested" objects? Could it possibly depend by the technology I use to implement that (Changing the model because of the technologies smells like bad practice though...)?

To give some context, I am using ASP.NET WebApi 2 for the backend and AngularJS in Typescript for the frontend

Answer 1

It depends on the experience you want the programmer to have as well as complexity and performance impact in your application.

• If the single object is large, and the consumer of the API does not need all the data upfront, then you might want to break it into multiple chunks, and have them call back if they want a related object.

• With larger objects, processing and performance on the server may increase, which might itself be an issue, so you may want to keep that lowered.

• On the other hand, if your object is really "incomplete" without the sub-objects, then you could consider sending them down in one go.

I do not think PK is necessarily a standard term that is understood by people other than those who deal with databases. For REST APIs, more suitable names might be EntryId, OrderId, MachineId etc., or more genericically Id and ObjectId, etc.

Also, you do not always need to send ObjectIds for the nested elements, the API itself will reveal the relationships (that is kind of the purpose of rest), and thus, from your example, the entry would like this:

entry{
  Id: "42",
  prop1: '_',
  prop2: '_',
}

If someone wanted to find all the orders for an entry, they will issue something like this:

https://www.example.com/entries/42/orders

This will get all the orders for the entry # 42 (with paging etc. if needed).

You might want to see this page for REST URL best practices, and this page for links to other best practices on Rest APIs. You might also want to look at OData since that deals primarily with data and is built on top of REST APIs. Do remember to obviously validate and get other opinions.