How to make REST-ful updates?

Question

If I have an object, tell Employee , and I want to offer two different ways to update it - update the performance rating or update the contact information.

What is a REST complete way to structure an API? I assume the correct method is POST.

I take care that for the user at first it seems IMPOSSIBLE to RECEIVE both parts of the object (performance rating and contact information), update only one part and POST of the entire updated object.

My other concern is that it seems that it is not elegant to send an object with only certain fields filled in, because the scheme requires all the fields for the object, and skipping fields is only for POST support. I. e. this requires separate circuits only to support operations or without circuits - not one of them seems correct.

Similarly, using flags for which fields to update also requires a different scheme for operation only.

The provision of individual methods does not fit into the paradigm of the noun-verb.

What should the REST API look like when they are needed to handle such cases? Should there be a multi-valued mapping between REST names and application entities? If so, are we restricting PUT to view objects that will represent a subset of the application entities?

I am not looking for hacking or an inelegant way. I am looking for the REST philosophy to consider the right solution. Thanks in advance!

Answer 1

I'm not sure if this is struggling with your problems, but, seeing how rating and information are also resources, I would make the API like that (thanks taylonr for the template :)

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

Thus, you can GET a representation of all employees, an employee with a specific identifier, a performance rating of an employee with a specific identifier and contact information for an employee with a specific identifier.

Creating a new employee with initialized contact information and a performance rating

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

Update 2 will work with different POST

 PUT url/employees/johnsmith/rating { "rating": 5 } PUT url/employees/johnsmith/info { "email": " [e-mail] " } 

Answer 2

I suppose it depends on how it is supposed to be used.

If you are just going to do something like simple, so that the client passes ALL the information necessary to update the ENTIRE Employee object, you only need to expose one endpoint, and you can just do ...

 domain/employee/{employee_id} 

As @taylonr explained. This is more of a script for the API that you advertise to third parties. The reason you create such a method is because it allows third parties to create their own functions to update the entire resource; and then pass it on to you. In other words, having all the available resources is a good catch; but probably not the best if you use it for your own web application.

But if this is the backend of a web application, and you are going to do something related; but does not require knowledge of all the information to complete the intended action, then you can follow this paradigm:

 domain/employee/{employee_id}/action 

So, for example, when I picked up your post, the message that Stackoverflow uses under the hood was ....

  noun noun verb verb | | | | | | | | http://stackoverflow.com/posts/8478829/vote/2 

The reason this is done is because all you need is a url and session information (your authenticated server-side object) and you can do whatever you need.

you said, that

My other concern is that it seems that it is not elegant to send an object with only certain fields filled in, because the scheme requires all the fields for the object, and skipping fields is only for POST support. I. e. this requires separate circuits only to support operations or without circuits - not one of them seems correct.

but I do not think that this is a real concern. Instead of relying on the client to convey all the information for the object that he would like to update, you simply use the "noun" part - posts/8478829 = and allow the resource server.

Answer 3

Why not just do

 PUT myuri/Employee/{id} 

And the request body has an Employee object. Thus, the consumer updates everything he wants and returns it to you. Since the user already has an identifier, you can do PUT.

As we usually do this on the API that I worked on.

The advantage of returning the entire object is that the API needs to know whether the version the user has is the most up-to-date (e.g. with ETag). If the consumer is trying to update something out of date, then it must fail.

Answer 4

PUT is also the URI with which you receive.

The REST API can have a one-to-one mapping between resources and things. Or a multi-valued comparison between resources and things. Only what “things” are is up to you; it may be what you consider the object of the application, but it is not necessary if it makes sense for it, for example. represent only part of such an object.

If I am a user of your API, I don’t care what you do or do not consider the entity in your implementation, I care about what you consider to be a resource in your web service.

Answer 5

Another option is to use the relatively new PATCH and custom schema for your patch / diff format. This allows you not to pollute the semantics of PUT / POST and more accurately match your needs, namely to update a subset of the resource attributes.

Otherwise, I would go with the Topy Oyal approach (PUT / POST exchange, as someone has already commented)