Allow sorting groups in APIsort-api-groups

Allow `order_by` and `sort` parameters to `/api/v3/groups.json`. At
present, only ordering by name and path is supported, and the default
sort is name ascending (alphabetical order).

4 files changed, 51 insertions, 3 deletions

diff --git a/changelogs/unreleased/sort-api-groups.yml b/changelogs/unreleased/sort-api-groups.yml
new file mode 100644
index 00000000000..e3eead8c04f
--- /dev/null
+++ b/changelogs/unreleased/sort-api-groups.yml
@@ -0,0 +1,4 @@
+---
+title: Allow sorting groups in the API
+merge_request:
+author:
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 45a3118f27a..5e6f498c365 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -6,8 +6,13 @@ Get a list of groups. (As user: my groups or all available, as admin: all groups
 
 Parameters:
 
-- `all_available` (optional) - if passed, show all groups you have access to
-- `skip_groups` (optional)(array of group IDs) - if passed, skip groups
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `skip_groups` | array of integers | no | Skip the group IDs passes |
+| `all_available` | boolean | no | Show all the groups you have access to |
+| `search` | string | no | Return list of authorized groups matching the search criteria |
+| `order_by` | string | no | Order groups by `name` or `path`. Default is `name` |
+| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` |
 
 ```
 GET /groups
diff --git a/lib/api/groups.rb b/lib/api/groups.rb
index 3f57b9ab5bc..48ad3b80ae0 100644
--- a/lib/api/groups.rb
+++ b/lib/api/groups.rb
@@ -19,6 +19,8 @@ module API
         optional :skip_groups, type: Array[Integer], desc: 'Array of group ids to exclude from list'
         optional :all_available, type: Boolean, desc: 'Show all group that you have access to'
         optional :search, type: String, desc: 'Search for a specific group'
+        optional :order_by, type: String, values: %w[name path], default: 'name', desc: 'Order by name or path'
+        optional :sort, type: String, values: %w[asc desc], default: 'asc', desc: 'Sort by asc (ascending) or desc (descending)'
       end
       get do
         groups = if current_user.admin
@@ -31,6 +33,8 @@ module API
 
         groups = groups.search(params[:search]) if params[:search].present?
         groups = groups.where.not(id: params[:skip_groups]) if params[:skip_groups].present?
+        groups = groups.reorder(params[:order_by] => params[:sort].to_sym)
+
         present paginate(groups), with: Entities::Group
       end
 
diff --git a/spec/requests/api/groups_spec.rb b/spec/requests/api/groups_spec.rb
index d79b204a24e..d9fdafde05e 100644
--- a/spec/requests/api/groups_spec.rb
+++ b/spec/requests/api/groups_spec.rb
@@ -57,13 +57,48 @@ describe API::API, api: true  do
     end
 
     context "when using all_available in request" do
+      let(:response_groups) { json_response.map { |group| group['name'] } }
+
       it "returns all groups you have access to" do
         public_group = create :group, :public
         get api("/groups", user1), all_available: true
 
         expect(response).to have_http_status(200)
         expect(json_response).to be_an Array
-        expect(json_response.first['name']).to eq(public_group.name)
+        expect(response_groups).to contain_exactly(public_group.name, group1.name)
+      end
+    end
+
+    context "when using sorting" do
+      let(:group3) { create(:group, name: "a#{group1.name}", path: "z#{group1.path}") }
+      let(:response_groups) { json_response.map { |group| group['name'] } }
+
+      before do
+        group3.add_owner(user1)
+      end
+
+      it "sorts by name ascending by default" do
+        get api("/groups", user1)
+
+        expect(response).to have_http_status(200)
+        expect(json_response).to be_an Array
+        expect(response_groups).to eq([group3.name, group1.name])
+      end
+
+      it "sorts in descending order when passed" do
+        get api("/groups", user1), sort: "desc"
+
+        expect(response).to have_http_status(200)
+        expect(json_response).to be_an Array
+        expect(response_groups).to eq([group1.name, group3.name])
+      end
+
+      it "sorts by the order_by param" do
+        get api("/groups", user1), order_by: "path"
+
+        expect(response).to have_http_status(200)
+        expect(json_response).to be_an Array
+        expect(response_groups).to eq([group1.name, group3.name])
       end
     end
   end