From 03fc3cc2c01fea3631af86b0b01a847722baf468 Mon Sep 17 00:00:00 2001 From: Changcheng Xiao Date: Mon, 23 Jul 2018 11:16:53 +0200 Subject: [PATCH] Guide users to use POST instead of DELETE for requests with bodies As our document says, some proxies prohibit DELETE requests with bodies. Proxies are not under client control. DELETE requests with bodies could work on a first attempt, but could fail afterwards because a server they have no control over was updated. Client users could be in trouble if they are not notified. Therefore, instead of explaining this potential problem to users in our doc, we always recommend POST to them whenever possible. For some cases, this commit just deletes thoese descriptions because they are not necessary or helpful. Change-Id: I5ed903ef1804022517942894f17d179070c6a342 --- Documentation/rest-api-changes.txt | 65 ++++++++++++----------------- Documentation/rest-api-projects.txt | 29 +++++++++---- 2 files changed, 47 insertions(+), 47 deletions(-) diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt index a26ffbcff1..cb3b88b0cc 100644 --- a/Documentation/rest-api-changes.txt +++ b/Documentation/rest-api-changes.txt @@ -924,10 +924,6 @@ If the topic was deleted the response is "`204 No Content`". Deletes the topic of a change. -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify a commit message, use -link:#set-topic[PUT] to delete the topic. - .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 @@ -2236,17 +2232,9 @@ If the change was already private the response is "`200 OK`". Marks the change to be non-private. Note users can only unmark own private changes. -A message can be specified in the request body inside a -link:#private-input[PrivateInput] entity. - .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0 - Content-Type: application/json; charset=UTF-8 - - { - "message": "This is a security fix that must not be public." - } ---- .Response @@ -2256,9 +2244,11 @@ link:#private-input[PrivateInput] entity. If the change was already not private, the response is "`409 Conflict`". -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to set a message options, use a -POST request: +A message can be specified in the request body inside a +link:#private-input[PrivateInput] entity. Historically, this method allowed +a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use a POST request instead: .Request ---- @@ -3132,18 +3122,17 @@ An email will be sent using the "newchange" template. Deletes a reviewer from a change. -Options can be provided in the request body as a -link:#delete-reviewer-input[DeleteReviewerInput] entity. - .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0 POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0 ---- -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify options, use a POST -request: +Options can be provided in the request body as a +link:#delete-reviewer-input[DeleteReviewerInput] entity. +Historically, this method allowed a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use a POST request instead: .Request ---- @@ -3213,18 +3202,17 @@ The entries in the map are sorted by label name. Deletes a single vote from a change. Note, that even when the last vote of a reviewer is removed the reviewer itself is still listed on the change. -Options can be provided in the request body as a -link:#delete-vote-input[DeleteVoteInput] entity. - .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0 POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 ---- -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify options, use a POST -request: +Options can be provided in the request body as a +link:#delete-vote-input[DeleteVoteInput] entity. +Historically, this method allowed a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use a POST request instead: .Request ---- @@ -4587,17 +4575,17 @@ describes the published comment. Deletes a published comment of a revision. Instead of deleting the whole comment, this endpoint just replaces the comment's message with a new message, which contains the name of the user who deletes -the comment and the reason why it's deleted. The reason can be -provided in the request body as a -link:#delete-comment-input[DeleteCommentInput] entity. +the comment and the reason why it's deleted. Note that only users with the link:access-control.html#capability_administrateServer[Administrate Server] global capability are permitted to delete a comment. -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify options, use a -POST request: +Deletion reason can be provided in the request body as a +link:#delete-comment-input[DeleteCommentInput] entity. +Historically, this method allowed a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use a POST request instead: .Request ---- @@ -5397,18 +5385,17 @@ deleting the vote (with same label) from a newer patch set by mistake. Note, that even when the last vote of a reviewer is removed the reviewer itself is still listed on the change. -Options can be provided in the request body as a -link:#delete-vote-input[DeleteVoteInput] entity. - .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review HTTP/1.0 POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 ---- -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify options, use a POST -request: +Options can be provided in the request body as a +link:#delete-vote-input[DeleteVoteInput] entity. +Historically, this method allowed a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use a POST request instead: .Request ---- diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt index 4a5cd1df03..22d4f0689c 100644 --- a/Documentation/rest-api-projects.txt +++ b/Documentation/rest-api-projects.txt @@ -597,14 +597,6 @@ If the description was deleted the response is "`204 No Content`". Deletes the description of a project. -The request body does not need to include a -link:#project-description-input[ProjectDescriptionInput] entity if no -commit message is specified. - -Please note that some proxies prohibit request bodies for DELETE -requests. In this case, if you want to specify a commit message, use -link:#set-project-description[PUT] to delete the description. - .Request ---- DELETE /projects/plugins%2Freplication/description HTTP/1.0 @@ -615,6 +607,27 @@ link:#set-project-description[PUT] to delete the description. HTTP/1.1 204 No Content ---- +A commit message can be provided in the request body as a +link:#project-description-input[ProjectDescriptionInput] entity. +Historically, this method allowed a body in the DELETE, but that behavior is +link:https://www.gerritcodereview.com/releases/2.16.md[deprecated]. +In this case, use link:#set-project-description[PUT] instead. + +.Request +---- + PUT /projects/plugins%2Freplication/description HTTP/1.0 + Content-Type: application/json; charset=UTF-8 + + { + "commit_message": "Update the project description" + } +---- + +.Response +---- + HTTP/1.1 204 No Content +---- + [[get-project-parent]] === Get Project Parent --