Merge branch 'improve-mr-api' into 'master'

Improve consistency and duplication for Merge Request API

* Follow REST for merge request API route
* Remove repeating comments API for MR
Signed-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>

Fixes #4759 and #11810 

See merge request !2639

CHANGELOG

@@ -14,6 +14,8 @@ v 8.5.0 (unreleased)
   - Track project import failure
   - Fix visibility level text in admin area (Zeger-Jan van de Weg)
   - Update the ExternalIssue regex pattern (Blake Hitchcock)
+  - Deprecate API "merge_request/:merge_request_id/comments". Use "merge_requests/:merge_request_id/notes" instead
+  - Deprecate API "merge_request/:merge_request_id/...". Use "merge_requests/:merge_request_id/..." instead
 
 v 8.4.2
   - Bump required gitlab-workhorse version to bring in a fix for missing

doc/api/merge_requests.md

@@ -60,7 +60,7 @@ Parameters:
 Shows information about a single merge request.
 
 ```
-GET /projects/:id/merge_request/:merge_request_id
+GET /projects/:id/merge_requests/:merge_request_id
 ```
 
 Parameters:
@@ -105,7 +105,7 @@ Parameters:
 Get a list of merge request commits.
 
 ```
-GET /projects/:id/merge_request/:merge_request_id/commits
+GET /projects/:id/merge_requests/:merge_request_id/commits
 ```
 
 Parameters:
@@ -142,7 +142,7 @@ Parameters:
 Shows information about the merge request including its files and changes.
 
 ```
-GET /projects/:id/merge_request/:merge_request_id/changes
+GET /projects/:id/merge_requests/:merge_request_id/changes
 ```
 
 Parameters:
@@ -264,7 +264,7 @@ If an error occurs, an error number and a message explaining the reason is retur
 Updates an existing merge request. You can change the target branch, title, or even close the MR.
 
 ```
-PUT /projects/:id/merge_request/:merge_request_id
+PUT /projects/:id/merge_requests/:merge_request_id
 ```
 
 Parameters:
@@ -323,7 +323,7 @@ If merge request is already merged or closed - you get 405 and error message 'Me
 If you don't have permissions to accept this merge request - you'll get a 401
 
 ```
-PUT /projects/:id/merge_request/:merge_request_id/merge
+PUT /projects/:id/merge_requests/:merge_request_id/merge
 ```
 
 Parameters:
@@ -373,7 +373,7 @@ If the merge request is already merged or closed - you get 405 and error message
 
 In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error.
 ```
-PUT /projects/:id/merge_request/:merge_request_id/cancel_merge_when_build_succeeds
+PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_build_succeeds
 ```
 Parameters:
 
@@ -409,66 +409,6 @@ Parameters:
 }
 ```
 
-## Post comment to MR
-
-Adds a comment to a merge request.
-
-```
-POST /projects/:id/merge_request/:merge_request_id/comments
-```
-
-Parameters:
-
-- `id` (required)               - The ID of a project
-- `merge_request_id` (required) - ID of merge request
-- `note` (required)             - Text of comment
-
-```json
-{
-  "note": "text1"
-}
-```
-
-## Get the comments on a MR
-
-Gets all the comments associated with a merge request.
-
-```
-GET /projects/:id/merge_request/:merge_request_id/comments
-```
-
-Parameters:
-
-- `id` (required)               - The ID of a project
-- `merge_request_id` (required) - ID of merge request
-
-```json
-[
-  {
-    "note": "this is the 1st comment on the 2merge merge request",
-    "author": {
-      "id": 11,
-      "username": "admin",
-      "email": "admin@example.com",
-      "name": "Administrator",
-      "state": "active",
-      "created_at": "2014-03-06T08:17:35.000Z"
-    }
-  },
-  {
-    "note": "Status changed to closed",
-    "author": {
-      "id": 11,
-      "username": "admin",
-      "email": "admin@example.com",
-      "name": "Administrator",
-      "state": "active",
-      "created_at": "2014-03-06T08:17:35.000Z"
-    }
-  }
-]
-```
-
 ## Comments on merge requets
 
-Comments are done via the notes resource.
+Comments are done via the [notes](notes.md) resource.

spec/requests/api/merge_requests_spec.rb

@@ -109,9 +109,9 @@ describe API::API, api: true  do
     end
   end
 
-  describe "GET /projects/:id/merge_request/:merge_request_id" do
+  describe "GET /projects/:id/merge_requests/:merge_request_id" do
     it "should return merge_request" do
-      get api("/projects/#{project.id}/merge_request/#{merge_request.id}", user)
+      get api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user)
       expect(response.status).to eq(200)
       expect(json_response['title']).to eq(merge_request.title)
       expect(json_response['iid']).to eq(merge_request.iid)
@@ -126,14 +126,14 @@ describe API::API, api: true  do
     end
 
     it "should return a 404 error if merge_request_id not found" do
-      get api("/projects/#{project.id}/merge_request/999", user)
+      get api("/projects/#{project.id}/merge_requests/999", user)
       expect(response.status).to eq(404)
     end
   end
 
-  describe 'GET /projects/:id/merge_request/:merge_request_id/commits' do
+  describe 'GET /projects/:id/merge_requests/:merge_request_id/commits' do
     context 'valid merge request' do
-      before { get api("/projects/#{project.id}/merge_request/#{merge_request.id}/commits", user) }
+      before { get api("/projects/#{project.id}/merge_requests/#{merge_request.id}/commits", user) }
       let(:commit) { merge_request.commits.first }
 
       it { expect(response.status).to eq 200 }
@@ -143,20 +143,20 @@ describe API::API, api: true  do
     end
 
     it 'returns a 404 when merge_request_id not found' do
-      get api("/projects/#{project.id}/merge_request/999/commits", user)
+      get api("/projects/#{project.id}/merge_requests/999/commits", user)
       expect(response.status).to eq(404)
     end
   end
 
-  describe 'GET /projects/:id/merge_request/:merge_request_id/changes' do
+  describe 'GET /projects/:id/merge_requests/:merge_request_id/changes' do
     it 'should return the change information of the merge_request' do
-      get api("/projects/#{project.id}/merge_request/#{merge_request.id}/changes", user)
+      get api("/projects/#{project.id}/merge_requests/#{merge_request.id}/changes", user)
       expect(response.status).to eq 200
       expect(json_response['changes'].size).to eq(merge_request.diffs.size)
     end
 
     it 'returns a 404 when merge_request_id not found' do
-      get api("/projects/#{project.id}/merge_request/999/changes", user)
+      get api("/projects/#{project.id}/merge_requests/999/changes", user)
       expect(response.status).to eq(404)
     end
   end
@@ -311,19 +311,19 @@ describe API::API, api: true  do
     end
   end
 
-  describe "PUT /projects/:id/merge_request/:merge_request_id to close MR" do
+  describe "PUT /projects/:id/merge_requests/:merge_request_id to close MR" do
     it "should return merge_request" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), state_event: "close"
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user), state_event: "close"
       expect(response.status).to eq(200)
       expect(json_response['state']).to eq('closed')
     end
   end
 
-  describe "PUT /projects/:id/merge_request/:merge_request_id/merge" do
+  describe "PUT /projects/:id/merge_requests/:merge_request_id/merge" do
     let(:ci_commit) { create(:ci_commit_without_jobs) }
 
     it "should return merge_request in case of success" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user)
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user)
 
       expect(response.status).to eq(200)
     end
@@ -332,7 +332,7 @@ describe API::API, api: true  do
       allow_any_instance_of(MergeRequest).
         to receive(:can_be_merged?).and_return(false)
 
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user)
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user)
 
       expect(response.status).to eq(406)
       expect(json_response['message']).to eq('Branch cannot be merged')
@@ -340,14 +340,14 @@ describe API::API, api: true  do
 
     it "should return 405 if merge_request is not open" do
       merge_request.close
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user)
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user)
       expect(response.status).to eq(405)
       expect(json_response['message']).to eq('405 Method Not Allowed')
     end
 
     it "should return 405 if merge_request is a work in progress" do
       merge_request.update_attribute(:title, "WIP: #{merge_request.title}")
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user)
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user)
       expect(response.status).to eq(405)
       expect(json_response['message']).to eq('405 Method Not Allowed')
     end
@@ -355,7 +355,7 @@ describe API::API, api: true  do
     it "should return 401 if user has no permissions to merge" do
       user2 = create(:user)
       project.team << [user2, :reporter]
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user2)
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user2)
       expect(response.status).to eq(401)
       expect(json_response['message']).to eq('401 Unauthorized')
     end
@@ -364,7 +364,7 @@ describe API::API, api: true  do
       allow_any_instance_of(MergeRequest).to receive(:ci_commit).and_return(ci_commit)
       allow(ci_commit).to receive(:active?).and_return(true)
 
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}/merge", user), merge_when_build_succeeds: true
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user), merge_when_build_succeeds: true
 
       expect(response.status).to eq(200)
       expect(json_response['title']).to eq('Test')
@@ -372,33 +372,33 @@ describe API::API, api: true  do
     end
   end
 
-  describe "PUT /projects/:id/merge_request/:merge_request_id" do
+  describe "PUT /projects/:id/merge_requests/:merge_request_id" do
     it "should return merge_request" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), title: "New title"
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user), title: "New title"
       expect(response.status).to eq(200)
       expect(json_response['title']).to eq('New title')
     end
 
     it "should return merge_request" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), description: "New description"
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user), description: "New description"
       expect(response.status).to eq(200)
       expect(json_response['description']).to eq('New description')
     end
 
     it "should return 400 when source_branch is specified" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user),
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user),
       source_branch: "master", target_branch: "master"
       expect(response.status).to eq(400)
     end
 
     it "should return merge_request with renamed target_branch" do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), target_branch: "wiki"
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}", user), target_branch: "wiki"
       expect(response.status).to eq(200)
       expect(json_response['target_branch']).to eq('wiki')
     end
 
     it 'should return 400 on invalid label names' do
-      put api("/projects/#{project.id}/merge_request/#{merge_request.id}",
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}",
               user),
           title: 'new issue',
           labels: 'label, ?'
@@ -407,11 +407,11 @@ describe API::API, api: true  do
     end
   end
 
-  describe "POST /projects/:id/merge_request/:merge_request_id/comments" do
+  describe "POST /projects/:id/merge_requests/:merge_request_id/comments" do
     it "should return comment" do
       original_count = merge_request.notes.size
 
-      post api("/projects/#{project.id}/merge_request/#{merge_request.id}/comments", user), note: "My comment"
+      post api("/projects/#{project.id}/merge_requests/#{merge_request.id}/comments", user), note: "My comment"
       expect(response.status).to eq(201)
       expect(json_response['note']).to eq('My comment')
       expect(json_response['author']['name']).to eq(user.name)
@@ -420,20 +420,20 @@ describe API::API, api: true  do
     end
 
     it "should return 400 if note is missing" do
-      post api("/projects/#{project.id}/merge_request/#{merge_request.id}/comments", user)
+      post api("/projects/#{project.id}/merge_requests/#{merge_request.id}/comments", user)
       expect(response.status).to eq(400)
     end
 
     it "should return 404 if note is attached to non existent merge request" do
-      post api("/projects/#{project.id}/merge_request/404/comments", user),
+      post api("/projects/#{project.id}/merge_requests/404/comments", user),
            note: 'My comment'
       expect(response.status).to eq(404)
     end
   end
 
-  describe "GET :id/merge_request/:merge_request_id/comments" do
+  describe "GET :id/merge_requests/:merge_request_id/comments" do
     it "should return merge_request comments ordered by created_at" do
-      get api("/projects/#{project.id}/merge_request/#{merge_request.id}/comments", user)
+      get api("/projects/#{project.id}/merge_requests/#{merge_request.id}/comments", user)
       expect(response.status).to eq(200)
       expect(json_response).to be_an Array
       expect(json_response.length).to eq(2)
@@ -443,7 +443,7 @@ describe API::API, api: true  do
     end
 
     it "should return a 404 error if merge_request_id not found" do
-      get api("/projects/#{project.id}/merge_request/999/comments", user)
+      get api("/projects/#{project.id}/merge_requests/999/comments", user)
       expect(response.status).to eq(404)
     end
   end