json - 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

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 https://www.rfc-editor.org/rfc/rfc5789

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