How to do REST-ful updates?

Question

If I have an object, say Employee, and I want to offer 2 different ways of updating it -- update performance rating, or update contact info.

What is the REST-ful way of structuring the API? I assume the right method is POST.

My concern is that it seems inelegant for a user to first GET both parts of the object (performance rating and contact info), update just one part, and POST the entire updated object.

My other concern is that it seems inelegant to sent an object with only certain fields filled in because the schema for the object requires all fields to be complete, and the omission of fields is only to support the POST. I. e. it would need separate schemas just to support the operations or doing without schemas -- neither of seems right.

Similarly, using flags for what fields to update also requires a different schema just for the operation.

Providing separate methods does not fit in any obvious way into the noun-verb paradigm.

HOW are REST APIs supposed to look when they are required to handle such cases? Does there need to be a many-to-one mapping between REST nouns and application entities? If so, do we restrict PUT for the view entities which would represent subsets of application entities?

I am not looking for a hack or an inelegant way. I am looking for what the REST philosophy would consider the right solution. Thanks in advance!

Answer 1

I'm not sure if this fights against your concerns, but seeing how Rating and Info are also resources I would make the API like this (thanks taylonr for the template :)

url/employees/{id}/[rating|info]

This way you can GET a representation of all the employees, an employee with a certain id, performance rating of an employee with a certain id and the contact info of an employee with a certain id.

Creating a new employee with initialized contact info and performance rating

POST url/employees { "id": "johnsmith", "rating": 4, "info": ["address": "street 1 a 1" , "email": "[email protected]"] }

Updating the 2 would work with different POSTs

PUT url/employees/johnsmith/rating  { "rating": 5 }
PUT url/employees/johnsmith/info { "email": "[email protected]" }