REST API Design for Updating Object Graph

Question

I'm designing a REST API and am looking for the recommended best practice for updating object graphs. My question is best explained in an example, so let's say that I have a GET resource as follows:

URI: /people/123

This URI returns an object graph like this:

{
    "name":"Johnny",
    "country":{"id":100,"name":"Canada"},
    "likes":[
        {"id":5,"name":"Fruit"},
        {"id":100,"name":"Sports"}
    ]
}

When allowing the API consumer to update this resource, how would you expect the object to be updated via PUT or PATCH? Updating the "name" property is pretty straightforward, but I'm not certain about "country" or "likes", as the consumer can only only change the relationship to other objects and not create new ones.

Here is one way to request the update:

{
    "name":"Bob",
    "countryId":200
    "likeIds":[3,10,22]
}

This update will change the resource to the following:

{
    "name":"Bob",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":3,"name":"Cars"},
        {"id":10,"name":"Planes"},
        {"id":22,"name":"Real Estate"}
    ]
}

This design explicitly and clearly asks the consumer to only update the "IDs" of the "Person", but I'm concerned that the object graph for a PUT/PATCH looks different than the GET, making the API hard to learn and remember. So another option is to request the PUT/PATCH as follows:

{
    "name":"Bob",
    "country":{"id":100},
    "likes":[
        {"id":3},
        {"id":10},
        {"id":22}
    ]
}

This will yield the same change as the previous update and does not alter the object graph. However, it doesn't make it clear to the API consumer that only the "IDs" can be updated.

In this scenario, which approach is recommended?

Answer 1

In my opinion you should stay with the same structure for both, GET and PUT requests. Why? Because it's quite common to map JSON/XML data into objects, and most (if not all) software that do the actual mapping work best if JSON schema is always the same.

So your webservice should accept a following JSON code:

{
    "name":"Joe",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":5,"name":"Fruit"}
    ]
}

However it doesn't have to take into account the country name and may focus only on the country id.