microsoft
Clarify PATCH/PUT semantics and versioning behavior
This PR contains two change requests:
-
The current guidelines say to use PATCH for create and update and to use PUT for wholesale create/update. I personally find it challenging to parse the difference between these two things. I was chatting with @tg-msft, and he said PATCH was recommended for update semantics and PUT was recommended for replace semantics, which I found easier to understand, and thought might be better to use to make the guidelines more self-explanatory. If guidelines authors like this edit, you might consider going farther to clarify that the replace semantics are the equivalent of DELETE followed by PUT regardless of the version of the client.
-
While it says elsewhere in the guidelines to fail an operation if a value isn't fully understood by the version of the service, the text in the section on "Create / Update / Replace Processing Rules" does not call out failing on properties unknown to the version explicitly. For clarity, it feels like it would be good to make this explicit in both places.
