API: Ability to update a group

CHANGELOG

@@ -12,6 +12,7 @@ v 8.7.0 (unreleased)
   - Make HTTP(s) label consistent on clone bar (Stan Hu)
   - Expose label description in API (Mariusz Jachimowicz)
   - Allow back dating on issues when created through the API
+  - API: Ability to update a group (Robert Schilling)
   - Fix Error 500 after renaming a project path (Stan Hu)
   - Fix avatar stretching by providing a cropping feature
   - API: Expose `subscribed` for issues and merge requests (Robert Schilling)

doc/api/groups.md

@@ -126,6 +126,87 @@ Parameters:
 - `id` (required) - The ID or path of a group
 - `project_id` (required) - The ID of a project
 
+## Update group
+
+Updates the project group. Only available to group owners and administrators.
+
+```
+PUT /groups/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the group |
+| `name` | string | no | The name of the group |
+| `path` | string | no | The path of the group |
+| `description` | string | no | The description of the group |
+| `visibility_level` | integer | no | The visibility_level of the group. 0 for private, 10 for internal, 20 for public. |
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/5?name=Experimental"
+
+```
+
+Example response:
+
+```json
+{
+  "id": 5,
+  "name": "Experimental",
+  "path": "h5bp",
+  "description": "foo",
+  "visibility_level": 10,
+  "avatar_url": null,
+  "web_url": "http://gitlab.example.com/groups/h5bp",
+  "projects": [
+    {
+      "id": 9,
+      "description": "foo",
+      "default_branch": "master",
+      "tag_list": [],
+      "public": false,
+      "archived": false,
+      "visibility_level": 10,
+      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
+      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
+      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
+      "name": "Html5 Boilerplate",
+      "name_with_namespace": "Experimental / Html5 Boilerplate",
+      "path": "html5-boilerplate",
+      "path_with_namespace": "h5bp/html5-boilerplate",
+      "issues_enabled": true,
+      "merge_requests_enabled": true,
+      "wiki_enabled": true,
+      "builds_enabled": true,
+      "snippets_enabled": true,
+      "created_at": "2016-04-05T21:40:50.169Z",
+      "last_activity_at": "2016-04-06T16:52:08.432Z",
+      "shared_runners_enabled": true,
+      "creator_id": 1,
+      "namespace": {
+        "id": 5,
+        "name": "Experimental",
+        "path": "h5bp",
+        "owner_id": null,
+        "created_at": "2016-04-05T21:40:49.152Z",
+        "updated_at": "2016-04-07T08:07:48.466Z",
+        "description": "foo",
+        "avatar": {
+          "url": null
+        },
+        "share_with_group_lock": false,
+        "visibility_level": 10
+      },
+      "avatar_url": null,
+      "star_count": 1,
+      "forks_count": 0,
+      "open_issues_count": 3,
+      "public_builds": true
+    }
+  ]
+}
+```
+
 ## Remove group
 
 Removes group with all projects inside.

lib/api/groups.rb

@@ -25,6 +25,8 @@ module API
       # Parameters:
       #   name (required)             - The name of the group
       #   path (required)             - The path of the group
+      #   description (optional)      - The description of the group
+      #   visibility_level (optional) - The visibility level of the group
       # Example Request:
       #   POST /groups
       post do
@@ -42,6 +44,30 @@ module API
         end
       end
 
+      # Update group. Available only for users who can administrate groups.
+      #
+      # Parameters:
+      #   id (required)                - The ID of a group
+      #   path (optional)             - The path of the group
+      #   description (optional)      - The description of the group
+      #   visibility_level (optional) - The visibility level of the group
+      # Example Request:
+      #   PUT /groups/:id
+      put ':id' do
+        group = find_group(params[:id])
+        authorize! :admin_group, group
+
+        attrs = attributes_for_keys [:name, :path, :description, :visibility_level]
+
+        ::Groups::UpdateService.new(group, current_user, attrs).execute
+
+        if group.errors.any?
+          render_validation_error!(group)
+        else
+          present group, with: Entities::GroupDetail
+        end
+      end
+
       # Get a single group, with containing projects
       #
       # Parameters:

spec/requests/api/groups_spec.rb

@@ -97,6 +97,42 @@ describe API::API, api: true  do
     end
   end
 
+  describe 'PUT /groups/:id' do
+    let(:new_group_name) { 'New Group'}
+
+    context "when authenticated the group owner" do
+      it 'updates the group' do
+        put api("/groups/#{group1.id}", user1), name: new_group_name
+
+        expect(response.status).to eq(200)
+        expect(json_response['name']).to eq(new_group_name)
+      end
+
+      it 'returns 404 for a non existing group' do
+        put api('/groups/1328', user1)
+
+        expect(response.status).to eq(404)
+      end
+    end
+
+    context "when authenticated the admin" do
+      it 'updates the group' do
+        put api("/groups/#{group1.id}", admin), name: new_group_name
+
+        expect(response.status).to eq(200)
+        expect(json_response['name']).to eq(new_group_name)
+      end
+    end
+
+    context "when authenticated an user" do
+      it 'updates the group' do
+        put api("/groups/#{group1.id}", user2), name: new_group_name
+
+        expect(response.status).to eq(403)
+      end
+    end
+  end
+
   describe "GET /groups/:id/projects" do
     context "when authenticated as user" do
       it "should return the group's projects" do