8

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

1 Answer 1

5

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.

2
  • Thanks for the suggestions. Can the fact that this is a sort of small enterprise application (will run in a factory) change some of the points you mentioned? Jun 25, 2014 at 2:32
  • If it's a small enterprise application, then one might favor simplicity of the API and application over the consumer experience. The counterside to that is that if the data model continues to change (e.g. entry gets more associations such as accounts, personnel, shipments, invoices, etc.) then one large object might not be suitable. Only you can decide what's more important and at stake, but you have a lesser problem of creating an API once that is hard to modify as is the case with public APIs (e.g. backward compatibility is usually a requirement).
    – Omer Iqbal
    Jun 25, 2014 at 3:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.