diff options
Diffstat (limited to 'doc/api/group_boards.md')
| -rw-r--r-- | doc/api/group_boards.md | 289 |
1 files changed, 279 insertions, 10 deletions
diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 9b0ac23b41c..4d10f83720b 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -5,7 +5,7 @@ Every API call to group boards must be authenticated. If a user is not a member of a group and the group is private, a `GET` request will result in `404` status code. -## Group Board +## List all group issue boards in a group Lists Issue Boards in the given group. @@ -27,7 +27,68 @@ Example response: [ { "id": 1, - "group_id": 5, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +] +``` + +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see +different parameters, due to the ability to have multiple group boards. + +Example response: + +```json +[ + { + "id": 1, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, "lists" : [ { "id" : 1, @@ -61,9 +122,9 @@ Example response: ] ``` -## Single board +## Single group issue board -Gets a single board. +Gets a single group issue board. ``` GET /groups/:id/boards/:board_id @@ -83,7 +144,66 @@ Example response: ```json { "id": 1, - "group_id": 5, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +``` + +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see +different parameters, due to the ability to have multiple group issue boards.s + +Example response: + +```json + { + "id": 1, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, "lists" : [ { "id" : 1, @@ -116,7 +236,156 @@ Example response: } ``` -## List board lists +## Create a group issue board **(PREMIUM)** + +Creates a Group Issue Board. + +``` +POST /groups/:id/boards +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the new board | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards?name=newboard +``` + +Example response: + +```json + { + "id": 1, + "name": "newboard", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +``` + +## Update a group issue board **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954) in GitLab 11.1. + +Updates a Group Issue Board. + +``` +PUT /groups/:id/boards/:board_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `board_id` | integer | yes | The ID of a board | +| `name` | string | no | The new name of the board | +| `assignee_id` | integer | no | The assignee the board should be scoped to | +| `milestone_id` | integer | no | The milestone the board should be scoped to | +| `labels` | string | no | Comma-separated list of label names which the board should be scoped to | +| `weight` | integer | no | The weight range from 0 to 9, to which the board should be scoped to | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4 +``` + +Example response: + +```json + { + "id": 1, + "project": null, + "lists": [], + "name": "new_name", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 44, + "iid": 1, + "group_id": 5, + "title": "Group Milestone", + "description": "Group Milestone Desc", + "state": "active", + "created_at": "2018-07-03T07:15:19.271Z", + "updated_at": "2018-07-03T07:15:19.271Z", + "due_date": null, + "start_date": null, + "web_url": "http://example.com/groups/documentcloud/-/milestones/1" + }, + "assignee": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://example.com/root" + }, + "labels": [{ + "id": 11, + "name": "GroupLabel", + "color": "#428BCA", + "description": "" + }], + "weight": 4 + } +``` + +## Delete a group issue board **(PREMIUM)** + +Deletes a Group Issue Board. + +``` +DELETE /groups/:id/boards/:board_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `board_id` | integer | yes | The ID of a board | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1 +``` + +## List group issue board lists Get a list of the board's lists. Does not include `open` and `closed` lists @@ -168,7 +437,7 @@ Example response: ] ``` -## Single board list +## Single group issue board list Get a single board list. @@ -200,7 +469,7 @@ Example response: } ``` -## New board list +## New group issue board list Creates a new Issue Board list. @@ -232,7 +501,7 @@ Example response: } ``` -## Edit board list +## Edit group issue board list Updates an existing Issue Board list. This call is used to change list position. @@ -265,7 +534,7 @@ Example response: } ``` -## Delete a board list +## Delete a group issue board list Only for admins and group owners. Soft deletes the board list in question. |