Refactor groups API documentationdoc_refactor_groups_api

[ci skip]

1 files changed, 458 insertions, 256 deletions

diff --git a/doc/api/groups.md b/doc/api/groups.md
index 808675d8605..928003310d0 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -1,256 +1,458 @@
-# Groups

-

-## List groups

-

-Get a list of groups. (As user: my groups, as admin: all groups)

-

-```

-GET /groups

-```

-

-```json

-[

-  {

-    "id": 1,

-    "name": "Foobar Group",

-    "path": "foo-bar",

-    "description": "An interesting group"

-  }

-]

-```

-

-You can search for groups by name or path, see below.

-

-

-## List a group's projects

-

-Get a list of projects in this group.

-

-```

-GET /groups/:id/projects

-```

-

-Parameters:

-

-- `archived` (optional) - if passed, limit by archived status

-- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`

-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`

-- `search` (optional) - Return list of authorized projects according to a search criteria

-- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first

-

-```json

-[

-  {

-    "id": 4,

-    "description": null,

-    "default_branch": "master",

-    "public": false,

-    "visibility_level": 0,

-    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",

-    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",

-    "web_url": "http://example.com/diaspora/diaspora-client",

-    "tag_list": [

-      "example",

-      "disapora client"

-    ],

-    "owner": {

-      "id": 3,

-      "name": "Diaspora",

-      "created_at": "2013-09-30T13: 46: 02Z"

-    },

-    "name": "Diaspora Client",

-    "name_with_namespace": "Diaspora / Diaspora Client",

-    "path": "diaspora-client",

-    "path_with_namespace": "diaspora/diaspora-client",

-    "issues_enabled": true,

-    "merge_requests_enabled": true,

-    "builds_enabled": true,

-    "wiki_enabled": true,

-    "snippets_enabled": false,

-    "created_at": "2013-09-30T13: 46: 02Z",

-    "last_activity_at": "2013-09-30T13: 46: 02Z",

-    "creator_id": 3,

-    "namespace": {

-      "created_at": "2013-09-30T13: 46: 02Z",

-      "description": "",

-      "id": 3,

-      "name": "Diaspora",

-      "owner_id": 1,

-      "path": "diaspora",

-      "updated_at": "2013-09-30T13: 46: 02Z"

-    },

-    "archived": false,

-    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png"

-  }

-]

-```

-

-## Details of a group

-

-Get all details of a group.

-

-```

-GET /groups/:id

-```

-

-Parameters:

-

-- `id` (required) - The ID or path of a group

-

-## New group

-

-Creates a new project group. Available only for users who can create groups.

-

-```

-POST /groups

-```

-

-Parameters:

-

-- `name` (required) - The name of the group

-- `path` (required) - The path of the group

-- `description` (optional) - The group's description

-

-## Transfer project to group

-

-Transfer a project to the Group namespace. Available only for admin

-

-```

-POST  /groups/:id/projects/:project_id

-```

-

-Parameters:

-

-- `id` (required) - The ID or path of a group

-- `project_id` (required) - The ID of a project

-

-## Remove group

-

-Removes group with all projects inside.

-

-```

-DELETE /groups/:id

-```

-

-Parameters:

-

-- `id` (required) - The ID or path of a user group

-

-## Search for group

-

-Get all groups that match your string in their name or path.

-

-```

-GET /groups?search=foobar

-```

-

-```json

-[

-  {

-    "id": 1,

-    "name": "Foobar Group",

-    "path": "foo-bar",

-    "description": "An interesting group"

-  }

-]

-```

-

-## Group members

-

-**Group access levels**

-

-The group access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized:

-

-```

-GUEST     = 10

-REPORTER  = 20

-DEVELOPER = 30

-MASTER    = 40

-OWNER     = 50

-```

-

-### List group members

-

-Get a list of group members viewable by the authenticated user.

-

-```

-GET /groups/:id/members

-```

-

-```json

-[

-  {

-    "id": 1,

-    "username": "raymond_smith",

-    "email": "ray@smith.org",

-    "name": "Raymond Smith",

-    "state": "active",

-    "created_at": "2012-10-22T14:13:35Z",

-    "access_level": 30

-  },

-  {

-    "id": 2,

-    "username": "john_doe",

-    "email": "joh@doe.org",

-    "name": "John Doe",

-    "state": "active",

-    "created_at": "2012-10-22T14:13:35Z",

-    "access_level": 30

-  }

-]

-```

-

-### Add group member

-

-Adds a user to the list of group members.

-

-```

-POST /groups/:id/members

-```

-

-Parameters:

-

-- `id` (required) - The ID or path of a group

-- `user_id` (required) - The ID of a user to add

-- `access_level` (required) - Project access level

-

-### Edit group team member

-

-Updates a group team member to a specified access level.

-

-```

-PUT /groups/:id/members/:user_id

-```

-

-Parameters:

-

-- `id` (required) - The ID of a group

-- `user_id` (required) - The ID of a group member

-- `access_level` (required) - Project access level

-

-### Remove user team member

-

-Removes user from user team.

-

-```

-DELETE /groups/:id/members/:user_id

-```

-

-Parameters:

-

-- `id` (required) - The ID or path of a user group

-- `user_id` (required) - The ID of a group member

-

-## Namespaces in groups

-

-By default, groups only get 20 namespaces at a time because the API results are paginated.

-

-To get more (up to 100), pass the following as an argument to the API call:

-```

-/groups?per_page=100

-```

-

-And to switch pages add:

-```

-/groups?per_page=100&page=2

-```

+# Groups
+
+Every API call to groups must be authenticated.
+
+If a user is not a member of a group and the group contains at least one private
+project, all API calls return a 403 status code.
+
+Groups use [pagination](README.md#pagination).
+
+## List groups
+
+Get a list of a user's groups. Administrators get a list of all groups.
+
+```
+GET /groups
+```
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups
+```
+
+Example response:
+
+```json
+[
+   {
+      "id" : 3,
+      "name" : "Gitlab Org",
+      "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+      "path" : "gitlab-org",
+      "avatar_url" : null,
+      "web_url" : "http://gitlab.example.com/groups/gitlab-org"
+   },
+]
+```
+
+## List a group's projects
+
+Get a list of projects in this group.
+
+```
+GET /groups/:id/projects
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID or path of a group |
+| `archived`| boolean | no  | If passed, limit by archived status |
+| `order_by`| string  | no  | Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`  |
+| `sort`    | string  | no  | Return requests sorted in `asc` or `desc` order. Default is `desc`
+| `search`  | string  | no  | Return list of authorized projects according to a search criteria
+| `ci_enabled_first`  |  -  | no  | Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/4/projects
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 4,
+    "description": null,
+    "default_branch": "master",
+    "public": false,
+    "visibility_level": 0,
+    "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
+    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
+    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
+    "tag_list": [
+      "example",
+      "disapora client"
+    ],
+    "owner": {
+      "id": 3,
+      "name": "Diaspora",
+      "created_at": "2013-09-30T13: 46: 02Z"
+    },
+    "name": "Diaspora Client",
+    "name_with_namespace": "Diaspora / Diaspora Client",
+    "path": "diaspora-client",
+    "path_with_namespace": "diaspora/diaspora-client",
+    "issues_enabled": true,
+    "merge_requests_enabled": true,
+    "builds_enabled": true,
+    "wiki_enabled": true,
+    "snippets_enabled": false,
+    "created_at": "2013-09-30T13: 46: 02Z",
+    "last_activity_at": "2013-09-30T13: 46: 02Z",
+    "creator_id": 3,
+    "namespace": {
+      "created_at": "2013-09-30T13: 46: 02Z",
+      "description": "",
+      "id": 3,
+      "name": "Diaspora",
+      "owner_id": 1,
+      "path": "diaspora",
+      "updated_at": "2013-09-30T13: 46: 02Z"
+    },
+    "archived": false,
+    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png"
+  }
+]
+```
+
+## Details of a group
+
+Get all details of a group by searching by name or by path.
+
+Every authenticated user can see the details of a group if there are no private
+projects in it.
+
+```
+GET /groups/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID or path of a group |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/3
+```
+
+Example response:
+
+```json
+[
+{
+  "web_url" : "http://gitlab.example.com/groups/gitlab-org",
+  "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+  "name" : "Gitlab Org",
+  "avatar_url" : null,
+  "path" : "gitlab-org",
+  "id" : 3,
+  "projects" : [
+     {
+        "tag_list" : [],
+        "path" : "gitlab-test",
+        "forks_count" : 0,
+        "default_branch" : "master",
+        "wiki_enabled" : true,
+        "last_activity_at" : "2015-09-15T18:34:17.834Z",
+        "http_url_to_repo" : "http://gitlab.example.com/gitlab-org/gitlab-test.git",
+        "archived" : false,
+        "id" : 5,
+        "star_count" : 0,
+        "avatar_url" : null,
+        "path_with_namespace" : "gitlab-org/gitlab-test",
+        "web_url" : "http://gitlab.example.com/gitlab-org/gitlab-test",
+        "merge_requests_enabled" : true,
+        "name_with_namespace" : "Gitlab Org / Gitlab Test",
+        "creator_id" : 1,
+        "snippets_enabled" : false,
+        "public" : true,
+        "issues_enabled" : true,
+        "namespace" : {
+           "avatar" : {
+              "url" : null
+           },
+           "owner_id" : null,
+           "path" : "gitlab-org",
+           "name" : "Gitlab Org",
+           "created_at" : "2015-09-15T18:24:44.162Z",
+           "updated_at" : "2015-09-15T18:24:44.162Z",
+           "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+           "id" : 3
+        },
+        "name" : "Gitlab Test",
+        "created_at" : "2015-09-15T18:27:31.969Z",
+        "ssh_url_to_repo" : "axil@gitlab.example.com:gitlab-org/gitlab-test.git",
+        "visibility_level" : 20,
+        "description" : "Veritatis harum culpa perferendis odit voluptates vel et."
+     },
+]
+```
+
+## New group
+
+Creates a new group. Available only for users who can create groups.
+
+```
+POST /groups
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `name` | string | yes | The name of the group |
+| `path` | string | yes | The path of the group |
+| `description` | string | no | The group's description |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups?path=my-group&name=My%20group"
+```
+
+Example response:
+
+```json
+{
+   "web_url" : "https://gitlab.example.com/groups/my-group",
+   "id" : 33,
+   "avatar_url" : null,
+   "description" : "",
+   "name" : "My group",
+   "path" : "my-group"
+}
+```
+
+## Transfer project to group
+
+Transfer a project to a Group namespace. Available only for admins.
+
+```
+POST  /groups/:id/projects/:project_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`         | integer | yes | The ID of a group |
+| `project_id` | integer | yes | The ID of a project |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/2/projects/9
+```
+
+Example response:
+
+```json
+{
+   "owner_id" : null,
+   "path" : "gitlab-org",
+   "created_at" : "2015-09-15T18:24:44.162Z",
+   "avatar" : {
+      "url" : null
+   },
+   "updated_at" : "2015-09-15T18:24:44.162Z",
+   "id" : 3,
+   "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+   "name" : "Gitlab Org"
+}
+```
+
+## Remove group
+
+Removes a group and all its projects.
+
+```
+DELETE /groups/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer/string | yes | The ID or path of a group |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/my-group
+```
+
+Example response:
+
+```json
+{
+   "avatar" : {
+      "url" : null
+   },
+   "created_at" : "2015-10-29T12:29:50.407Z",
+   "updated_at" : "2015-10-29T12:29:50.407Z",
+   "description" : "",
+   "path" : "my-group",
+   "name" : "My group",
+   "id" : 33,
+   "owner_id" : null
+}
+```
+
+## Search for group
+
+Get all groups that match a string in their name or path.
+
+```
+GET /groups?search=foobar
+```
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups?search=gitlab"
+```
+
+Example response:
+
+```json
+[
+   {
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/groups/gitlab-org",
+      "path" : "gitlab-org",
+      "name" : "Gitlab Org",
+      "id" : 3,
+      "description" : "Quae magnam libero provident non illum quidem vel fugit."
+   }
+]
+```
+
+## Group members
+
+**Group access levels**
+
+The group access levels are defined in the `Gitlab::Access` module. Currently,
+these levels are recognized:
+
+```
+GUEST     = 10
+REPORTER  = 20
+DEVELOPER = 30
+MASTER    = 40
+OWNER     = 50
+```
+
+### List group members
+
+Get a list of group members viewable by the authenticated user.
+
+```
+GET /groups/:id/members
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of a group |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/3/members
+```
+
+Example response:
+
+```json
+[
+   {
+      "username" : "peyton",
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/u/peyton",
+      "state" : "active",
+      "id" : 11,
+      "name" : "Sarai Walter",
+      "access_level" : 20
+   },
+   {
+      "access_level" : 20,
+      "name" : "Mallie Jacobs",
+      "id" : 5,
+      "state" : "active",
+      "web_url" : "https://gitlab.example.com/u/hazle",
+      "avatar_url" : null,
+      "username" : "hazle"
+   },
+]
+```
+
+### Add group member
+
+Adds a user to the list of group members.
+
+```
+POST /groups/:id/members
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+| `access_level` | integer | yes | The access level a user will have |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members?user_id=7&access_level=30"
+```
+
+Example response:
+
+```json
+{
+   "web_url" : "https://gitlab.example.com/u/laurine",
+   "username" : "laurine",
+   "state" : "active",
+   "id" : 7,
+   "access_level" : 30,
+   "name" : "Dr. Meta Fritsch",
+   "avatar_url" : null
+}
+```
+
+### Edit group member
+
+Updates a group team member to a specified access level.
+
+```
+PUT /groups/:id/members/:user_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+| `access_level` | integer | yes | The group access level a user will have |
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members/7?access_level=20"
+```
+
+Example response:
+
+```json
+{
+   "web_url" : "https://gitlab.example.com/u/laurine",
+   "username" : "laurine",
+   "state" : "active",
+   "id" : 7,
+   "access_level" : 20,
+   "name" : "Dr. Meta Fritsch",
+   "avatar_url" : null
+}
+```
+
+### Remove user from group
+
+Removes a user from a group.
+
+```
+DELETE /groups/:id/members/:user_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members/7"
+```
+
+Example response:
+
+```json
+{
+   "source_type" : "Namespace",
+   "invite_accepted_at" : null,
+   "updated_at" : "2015-10-29T15:11:59.687Z",
+   "notification_level" : 3,
+   "id" : 60,
+   "invite_token" : null,
+   "access_level" : 10,
+   "created_at" : "2015-10-29T15:02:39.659Z",
+   "created_by_id" : 26,
+   "invite_email" : null,
+   "user_id" : 7,
+   "source_id" : 3
+}
+```