Update documentation

changelogs/unreleased/api-empty-return.yml

+---
+title: 'API: Return 204 for all delete endpoints'
+merge_request: 9397
+author: Robert Schilling

doc/api/README.md

@@ -159,6 +159,7 @@ The following table shows the possible return codes for API requests.
 | Return values | Description |
 | ------------- | ----------- |
 | `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
+| `204 OK` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
 | `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
 | `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
 | `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |

doc/api/award_emoji.md

@@ -178,27 +178,6 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/344
 ```
-Example Response:
-
-```json
-{
-  "id": 344,
-  "name": "blowfish",
-  "user": {
-    "name": "Administrator",
-    "username": "root",
-    "id": 1,
-    "state": "active",
-    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
-    "web_url": "http://gitlab.example.com/root"
-  },
-  "created_at": "2016-06-17T17:47:29.266Z",
-  "updated_at": "2016-06-17T17:47:29.266Z",
-  "awardable_id": 80,
-  "awardable_type": "Issue"
-}
-```
-
 ## Award Emoji on Notes
 The endpoints documented above are available for Notes as well. Notes
@@ -350,25 +329,4 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/345
 ```
-Example Response:
-
-```json
-{
-  "id": 345,
-  "name": "rocket",
-  "user": {
-    "name": "Administrator",
-    "username": "root",
-    "id": 1,
-    "state": "active",
-    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
-    "web_url": "http://gitlab.example.com/root"
-  },
-  "created_at": "2016-06-17T19:59:55.888Z",
-  "updated_at": "2016-06-17T19:59:55.888Z",
-  "awardable_id": 1,
-  "awardable_type": "Note"
-}
-```
-
 [ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575

doc/api/boards.md

@@ -226,16 +226,3 @@ DELETE /projects/:id/boards/:board_id/lists/:list_id
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/boards/1/lists/1
 ```
-Example response:
-
-```json
-{
-  "id" : 1,
-  "label" : {
-    "name" : "Testing",
-    "color" : "#F0AD4E",
-    "description" : null
-  },
-  "position" : 1
-}
-```

doc/api/branches.md

@@ -244,14 +244,6 @@ In case of an error, an explaining message is provided.
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
 ```
-Example response:
-
-```json
-{
-  "branch_name": "newbranch"
-}
-```
-
 ## Delete merged branches
 Will delete all branches that are merged into the project's default branch.

doc/api/broadcast_messages.md

@@ -138,17 +138,3 @@ DELETE /broadcast_messages/:id
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages/1
 ```
-
-Example response:
-
-```json
-{
-    "message":"Update message",
-    "starts_at":"2016-08-26T00:41:35.060Z",
-    "ends_at":"2016-08-26T01:41:35.060Z",
-    "color":"#000",
-    "font":"#FFFFFF",
-    "id":1,
-    "active": true
-}
-```

doc/api/build_triggers.md

@@ -106,13 +106,3 @@ DELETE /projects/:id/triggers/:token
 ```
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d"
 ```
-
-```json
-{
-    "created_at": "2015-12-23T16:25:56.760Z",
-    "deleted_at": "2015-12-24T12:32:20.100Z",
-    "last_used": null,
-    "token": "7b9148c158980bbd9bcea92c17522d",
-    "updated_at": "2015-12-24T12:32:20.100Z"
-}
-```

doc/api/build_variables.md

@@ -119,10 +119,3 @@ DELETE /projects/:id/variables/:key
 ```
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/VARIABLE_1"
 ```
-
-```json
-{
-    "key": "VARIABLE_1",
-    "value": "VALUE_1"
-}
-```

doc/api/deploy_keys.md

@@ -152,18 +152,6 @@ DELETE /projects/:id/deploy_keys/:key_id
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/deploy_keys/13"
 ```
-Example response:
-
-```json
-{
-  "id": 6,
-  "deploy_key_id": 14,
-  "project_id": 1,
-  "created_at" : "2015-08-29T12:50:57.259Z",
-  "updated_at" : "2015-08-29T12:50:57.259Z"
-}
-```
-
 ## Enable a deploy key
 Enables a deploy key for a project so this can be used. Returns the enabled key, with a status code 201 when successful.

doc/api/enviroments.md

@@ -108,14 +108,3 @@ DELETE /projects/:id/environments/:environment_id
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/environments/1"
 ```
-
-Example response:
-
-```json
-{
-  "id": 1,
-  "name": "deploy",
-  "slug": "deploy",
-  "external_url": "https://deploy.example.gitlab.com"
-}
-```

doc/api/issues.md

@@ -581,43 +581,6 @@ POST /projects/:id/issues/:issue_id/unsubscribe
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/unsubscribe
 ```
-Example response:
-
-```json
-{
-  "id": 93,
-  "iid": 12,
-  "project_id": 5,
-  "title": "Incidunt et rerum ea expedita iure quibusdam.",
-  "description": "Et cumque architecto sed aut ipsam.",
-  "state": "opened",
-  "created_at": "2016-04-05T21:41:45.217Z",
-  "updated_at": "2016-04-07T13:02:37.905Z",
-  "labels": [],
-  "milestone": null,
-  "assignee": {
-    "name": "Edwardo Grady",
-    "username": "keyon",
-    "id": 21,
-    "state": "active",
-    "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon",
-    "web_url": "https://gitlab.example.com/keyon"
-  },
-  "author": {
-    "name": "Vivian Hermann",
-    "username": "orville",
-    "id": 11,
-    "state": "active",
-    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
-    "web_url": "https://gitlab.example.com/orville"
-  },
-  "subscribed": false,
-  "due_date": null,
-  "web_url": "http://example.com/example/example/issues/12",
-  "confidential": false
-}
-```
-
 ## Create a todo
 Manually creates a todo for the current user on an issue. If

doc/api/labels.md

@@ -131,22 +131,6 @@ DELETE /projects/:id/labels
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
 ```
-Example response:
-
-```json
-{
-  "id" : 1,
-  "name" : "bug",
-  "color" : "#d9534f",
-  "description": "Bug reported by user",
-  "open_issues_count": 1,
-  "closed_issues_count": 0,
-  "open_merge_requests_count": 1,
-  "subscribed": false,
-  "priority": null
-}
-```
-
 ## Edit an existing label
 Updates an existing label with new name or new color. At least one parameter
@@ -239,19 +223,3 @@ POST /projects/:id/labels/:label_id/unsubscribe
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/labels/1/unsubscribe
 ```
-
-Example response:
-
-```json
-{
-  "id" : 1,
-  "name" : "bug",
-  "color" : "#d9534f",
-  "description": "Bug reported by user",
-  "open_issues_count": 1,
-  "closed_issues_count": 0,
-  "open_merge_requests_count": 1,
-  "subscribed": false,
-  "priority": null
-}
-```

doc/api/notes.md

@@ -123,30 +123,6 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/11/notes/636
 ```
-Example Response:
-
-```json
-{
-  "id": 636,
-  "body": "This is a good idea.",
-  "attachment": null,
-  "author": {
-    "id": 1,
-    "username": "pipin",
-    "email": "admin@example.com",
-    "name": "Pip",
-    "state": "active",
-    "created_at": "2013-09-30T13:46:01Z",
-    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
-    "web_url": "https://gitlab.example.com/pipin"
-  },
-  "created_at": "2016-04-05T22:10:44.164Z",
-  "system": false,
-  "noteable_id": 11,
-  "noteable_type": "Issue"
-}
-```
-
 ## Snippets
 ### List all snippet notes
@@ -245,30 +221,6 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/snippets/52/notes/1659
 ```
-Example Response:
-
-```json
-{
-  "id": 1659,
-  "body": "This is a good idea.",
-  "attachment": null,
-  "author": {
-    "id": 1,
-    "username": "pipin",
-    "email": "admin@example.com",
-    "name": "Pip",
-    "state": "active",
-    "created_at": "2013-09-30T13:46:01Z",
-    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
-    "web_url": "https://gitlab.example.com/pipin"
-  },
-  "created_at": "2016-04-06T16:51:53.239Z",
-  "system": false,
-  "noteable_id": 52,
-  "noteable_type": "Snippet"
-}
-```
-
 ## Merge Requests
 ### List all merge request notes
@@ -369,27 +321,3 @@ Parameters:
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/7/notes/1602
 ```
-
-Example Response:
-
-```json
-{
-  "id": 1602,
-  "body": "This is a good idea.",
-  "attachment": null,
-  "author": {
-    "id": 1,
-    "username": "pipin",
-    "email": "admin@example.com",
-    "name": "Pip",
-    "state": "active",
-    "created_at": "2013-09-30T13:46:01Z",
-    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
-    "web_url": "https://gitlab.example.com/pipin"
-  },
-  "created_at": "2016-04-05T22:11:59.923Z",
-  "system": false,
-  "noteable_id": 7,
-  "noteable_type": "MergeRequest"
-}
-```

doc/api/runners.md

@@ -210,18 +210,6 @@ DELETE /runners/:id
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6"
 ```
-Example response:
-
-```json
-{
-    "active": true,
-    "description": "test-1-20150125-test",
-    "id": 6,
-    "is_shared": false,
-    "name": null,
-}
-```
-
 ## List project's runners
 List all runners (specific and shared) available in the project. Shared runners
@@ -308,15 +296,3 @@ DELETE /projects/:id/runners/:runner_id
 ```
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners/9"
 ```
-
-Example response:
-
-```json
-{
-    "active": true,
-    "description": "test-2016-02-01",
-    "id": 9,
-    "is_shared": false,
-    "name": null
-}
-```

doc/api/system_hooks.md

@@ -125,22 +125,3 @@ Example request:
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
 ```
-
-Example response:
-
-```json
-{
-   "note_events" : false,
-   "project_id" : null,
-   "enable_ssl_verification" : true,
-   "url" : "https://gitlab.example.com/hook",
-   "updated_at" : "2015-11-04T20:12:15.931Z",
-   "issues_events" : false,
-   "merge_requests_events" : false,
-   "created_at" : "2015-11-04T20:12:15.931Z",
-   "service_id" : null,
-   "id" : 2,
-   "push_events" : true,
-   "tag_push_events" : false
-}
-```

doc/api/tags.md

@@ -141,11 +141,6 @@ Parameters:
 - `id` (required) - The ID of a project
 - `tag_name` (required) - The name of a tag
-```json
-{
-  "tag_name": "v4.3.0"
-}
-```
 ## Create a new release