https://gitlab.com/gitlab-org/gitlab/-/issues/211864 - Support reordering of issues via the api

changelogs/unreleased/35349-reorder-api.yml

+---
+title: "Added support for reordering issues to the v4 API"
+merge_request: 35349
+author: Joel @jjshoe, Lee Tickett @leetickett
+type: added

doc/api/issues.md

@@ -901,6 +901,25 @@ DELETE /projects/:id/issues/:issue_iid
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85"
 ```
 
+## Reorder an issue
+
+Reorders an issue, you can see the results when sorting issues manually
+
+```plaintext
+PUT /projects/:id/issues/:issue_iid/reorder
+```
+
+| Attribute   | Type    | Required | Description                          |
+|-------------|---------|----------|--------------------------------------|
+| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
+| `move_after_id` | integer | no | The ID of a projet's issue to move this issue after |
+| `move_before_id` | integer | no | The ID of a projet's issue to move this issue before |
+
+```shell
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92"
+```
+
 ## Move an issue
 
 Moves an issue to a different project. If the target project

lib/api/issues.rb

@@ -289,6 +289,30 @@ module API
       end
       # rubocop: enable CodeReuse/ActiveRecord
 
+      desc 'Reorder an existing issue' do
+        success Entities::Issue
+      end
+      params do
+        requires :issue_iid, type: Integer, desc: 'The internal ID of a project issue'
+        optional :move_after_id, type: Integer, desc: 'The ID of the issue we want to be after'
+        optional :move_before_id, type: Integer, desc: 'The ID of the issue we want to be before'
+        at_least_one_of :move_after_id, :move_before_id
+      end
+      # rubocop: disable CodeReuse/ActiveRecord
+      put ':id/issues/:issue_iid/reorder' do
+        issue = user_project.issues.find_by(iid: params[:issue_iid])
+        not_found!('Issue') unless issue
+
+        authorize! :update_issue, issue
+
+        if ::Issues::ReorderService.new(user_project, current_user, params).execute(issue)
+          present issue, with: Entities::Issue, current_user: current_user, project: user_project
+        else
+          render_api_error!({ error: 'Unprocessable Entity' }, 422)
+        end
+      end
+      # rubocop: enable CodeReuse/ActiveRecord
+
       desc 'Move an existing issue' do
         success Entities::Issue
       end

spec/requests/api/issues/issues_spec.rb

@@ -886,4 +886,53 @@ RSpec.describe API::Issues do
 
     include_examples 'time tracking endpoints', 'issue'
   end
+
+  describe 'PUT /projects/:id/issues/:issue_iid/reorder' do
+    let_it_be(:project) { create(:project) }
+    let_it_be(:issue1) { create(:issue, project: project, relative_position: 10) }
+    let_it_be(:issue2) { create(:issue, project: project, relative_position: 20) }
+    let_it_be(:issue3) { create(:issue, project: project, relative_position: 30) }
+
+    context 'when user has access' do
+      before do
+        project.add_developer(user)
+      end
+
+      context 'with valid params' do
+        it 'reorders issues and returns a successful 200 response' do
+          put api("/projects/#{project.id}/issues/#{issue1.iid}/reorder", user), params: { move_after_id: issue2.id, move_before_id: issue3.id }
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(issue1.reload.relative_position)
+                .to be_between(issue2.reload.relative_position, issue3.reload.relative_position)
+        end
+      end
+
+      context 'with invalid params' do
+        it 'returns a unprocessable entity 422 response for invalid move ids' do
+          put api("/projects/#{project.id}/issues/#{issue1.iid}/reorder", user), params: { move_after_id: issue2.id, move_before_id: non_existing_record_id }
+
+          expect(response).to have_gitlab_http_status(:unprocessable_entity)
+        end
+
+        it 'returns a not found 404 response for invalid issue id' do
+          put api("/projects/#{project.id}/issues/#{non_existing_record_iid}/reorder", user), params: { move_after_id: issue2.id, move_before_id: issue3.id }
+
+          expect(response).to have_gitlab_http_status(:not_found)
+        end
+      end
+    end
+
+    context 'with unauthorized user' do
+      before do
+        project.add_guest(user)
+      end
+
+      it 'responds with 403 forbidden' do
+        put api("/projects/#{project.id}/issues/#{issue1.iid}/reorder", user), params: { move_after_id: issue2.id, move_before_id: issue3.id }
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+  end
 end