Merge branch 'fix-api-docs' into 'master'

Fix wrong API status codes

See merge request !14069

4 files changed, 7 insertions, 17 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index a947eed2db8..db61497db53 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -237,8 +237,8 @@ The following table gives an overview of how the API functions generally behave.
 | ------------ | ----------- |
 | `GET`   | Access one or more resources and return the result as JSON. |
 | `POST`  | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
-| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
-| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
+| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
+| `DELETE` | Returns `204 No Content` if the resuource was deleted successfully. |
 
 The following table shows the possible return codes for API requests.
 
diff --git a/doc/api/environments.md b/doc/api/environments.md
index 5ca766bf87d..e8deb3e07e9 100644
--- a/doc/api/environments.md
+++ b/doc/api/environments.md
@@ -94,7 +94,7 @@ Example response:
 
 ## Delete an environment
 
-It returns `200` if the environment was successfully deleted, and `404` if the environment does not exist.
+It returns `204` if the environment was successfully deleted, and `404` if the environment does not exist.
 
 ```
 DELETE /projects/:id/environments/:environment_id
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index 24c8ff5fa7a..ad2521230e6 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -95,8 +95,7 @@ Parameters:
 
 ## Delete snippet
 
-Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
-snippet still returns a `200 OK` status code.
+Deletes an existing project snippet. This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
 
 ```
 DELETE /projects/:id/snippets/:snippet_id
diff --git a/doc/api/users.md b/doc/api/users.md
index 57b4e117cf3..9f3e4caf2f4 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -299,10 +299,7 @@ e.g. when renaming the email address to some existing one.
 ## User deletion
 
 Deletes a user. Available only for administrators.
-This is an idempotent function, calling this function for a non-existent user id
-still returns a status code `200 OK`.
-The JSON response differs if the user was actually deleted or not.
-In the former the user is returned and in the latter not.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
 
 ```
 DELETE /users/:id
@@ -524,8 +521,7 @@ Parameters:
 ## Delete SSH key for current user
 
 Deletes key owned by currently authenticated user.
-This is an idempotent function and calling it on a key that is already deleted
-or not available results in `200 OK`.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
 
 ```
 DELETE /user/keys/:key_id
@@ -548,8 +544,6 @@ Parameters:
 - `id` (required) - id of specified user
 - `key_id` (required)  - SSH key ID
 
-Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
-
 ## List all GPG keys
 
 Get a list of currently authenticated user's GPG keys.
@@ -865,8 +859,7 @@ Parameters:
 ## Delete email for current user
 
 Deletes email owned by currently authenticated user.
-This is an idempotent function and calling it on a email that is already deleted
-or not available results in `200 OK`.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
 
 ```
 DELETE /user/emails/:email_id
@@ -889,8 +882,6 @@ Parameters:
 - `id` (required) - id of specified user
 - `email_id` (required)  - email ID
 
-Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
-
 ## Block user
 
 Blocks the specified user.  Available only for admin.