Question

I’d like some feedback on my current architecture.

I have a “Person” resource that is available through GET and PUT requests to: /users/people/{key}. The resource produces and accepts “Person” objects in JSON format.

This is an example of the JSON that GET /users/people/{key} might return:

{
 "age":29,
 "firstName":"Chiquita",
 "phoneNumbers":[
   {"key":"49fnfnsa0sas","number":"555-555-5555","deleted":false}
   {"key":"838943bdfb-f","number":"777-777-7777","deleted":false}
  ]
}

As you can see, “Person” has some typical fields such as “firstName” and “age” as well as a trickier collection-type field: “phoneNumbers”.

I’m trying to design the resources so that when updating them, the client only needs to send back the fields that need to be updated. For example, to update only the person’s firstName:

PUT users/people/{key}

{
 "firstName":"New first name",
}

This way there is a lot less unnecessary information being transferred back and forth (degrees of magnitude less depending on the size of the the resource)

My question is, what should I do with the list properties such as “phoneNumbers.” Should I write some more complex code that examines the existing PhoneNumber keys in the old list and doesn’t touch them if they are not referenced, updates them if there is a matching key, and adds them if there is a PhoneNumber with a new key? Or should I write some simpler code that treats each “phoneNumbers” list property as just another field that is completely overwritten if it is included in the “PUT” request body? Is there a standard accepted approach to this where one strategy has been proven to be less problematic than another? or am I to use my discretion?

Thanks!

Answer 1

I’m thinking it’d make the most sense to simply have the client upload all the info for the current person every time something is changed. However, this might not be adequate if:

• A lot of data would have to be sent back and forth per change in typical scenarios.
• Multiple people can edit the same person simultaneously.

If your people objects are large, you might consider taking a diff/patch approach. Before sending the new version, compare it to the old version. If a singleton field (e.g. firstName) changed, simply list it in your JSON object:

{
 "firstName":"New first name"
}

For the array of phone numbers, list the phone numbers to remove by key, and list the new phone numbers to add like you normally would. Something like this:

{
 "+phoneNumbers":[
  {"key":"123456789abc","number":"555-123-4567"}
 ],
 "-phoneNumbers":[
  "49fnfnsa0sas"
 ]
}

You could also Google search “json diff” and see if any of the results you find are helpful.

As I said before, unless you have a compelling reason to go to this depth of complexity, it’s probably best to just have the client re-upload the entire person object to update it.