在基于JSON的REST API上进行PUT的最常见预期行为是什么？ 文档替换或部分更新）？

Question

I know there's a whole RFC for HTTP methods but I was wondering what would be the expected behaviour from a PUT to a REST API that responds with Content-type: application/json and accepts JSON encoded bodies.

• Is it expected to replace the document entirely with the new JSON object passed in the body?
• Is it expected to modify only the attributes passed in the JSON body? (as its the recommended behaviour for the PATCH method RFC 5789 ).
• What if the documents that the API exposes do not conform to an schema and the JSON object in the body has new properties not present in the current document?. Should it add them?

Any comment or resource for me to read will be welcome .

Answer 1

1) and 2) PUT means replace. Using it for partial replacement is incorrect. That's what PATCH is for.

3) That's up to your application logic.

Answer 2

In practice, either of those approaches is all right as long you stick to it throughout the whole application so you keep consistency. I personally like to use PUT if I want to update all the attributes of a record according to the ID. This way I can save the PATCH method for endpoints where I need to specify and update only some attributes like the a typical change password request where I only need to update a specific attribute.

I really recommend this book: http://www.amazon.com/REST-API-Design-Handbook-ebook/dp/B00890OBFI/ref=sr_1_2?s=books&ie=UTF8&qid=1425669926&sr=1-2&keywords=rest+api