REST resource with a List property

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.

Answer 2

The definition of a PUT is that it must have replace semantics. The PATCH verb was introduced to allow the possibility of doing partial updates. See http://tools.ietf.org/html/rfc5789

As for how to do the diff format, there really is no right or wrong way. It really depends on your context.

Answer 3

As the others have said, PUT requires replacement of the entire resource. However, as the architect you get to design what the resource is. Maybe the Person record has the phone numbers as part of it. Or maybe it's more like the way you would set up a relational database with phone numbers in a separate table. In that case GET /users/people/{key} would get only the name and age, and you would define query parameters if you want a way to get the phone numbers along with the name. GET /users/userphone/{key} would get the resource containing the person's phone numbers, an array.

Going back to defining the Person resource as containing the phone numbers within it, there is nothing wrong with using POST. For instance, the classic use of POST is to post a comment to a web page or delete a comment. There is no reason you can't define a POST operation to add or remove a phone number. POST is the anything-goes method, for good or ill.

(I notice the button here says "Post Your Answer", not "Put Your Answer", and for good reason.)