Merge branch '27142-api-replace-destroy-with-stop-environment' into 'master'

API: Add environment action with /stop action

Closes #27142

See merge request !8808

2 files changed, 32 insertions, 3 deletions

diff --git a/doc/api/enviroments.md b/doc/api/enviroments.md
index e510f723e26..61677569254 100644
--- a/doc/api/enviroments.md
+++ b/doc/api/enviroments.md
@@ -33,7 +33,7 @@ Example response:
 
 Creates a new environment with the given name and external_url.
 
-It returns 201 if the environment was successfully created, 400 for wrong parameters.
+It returns `201` if the environment was successfully created, `400` for wrong parameters.
 
 ```
 POST /projects/:id/environment
@@ -64,7 +64,7 @@ Example response:
 
 Updates an existing environment's name and/or external_url.
 
-It returns 200 if the environment was successfully updated. In case of an error, a status code 400 is returned.
+It returns `200` if the environment was successfully updated. In case of an error, a status code `400` is returned.
 
 ```
 PUT /projects/:id/environments/:environments_id
@@ -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 `200` if the environment was successfully deleted, and `404` if the environment does not exist.
 
 ```
 DELETE /projects/:id/environments/:environment_id
@@ -108,3 +108,31 @@ DELETE /projects/:id/environments/:environment_id
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/environments/1"
 ```
+
+## Stop an environment
+
+It returns `200` if the environment was successfully stopped, and `404` if the environment does not exist.
+
+```
+POST /projects/:id/environments/:environment_id/stop
+```
+
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id` | integer | yes | The ID of the project |
+| `environment_id` | integer | yes | The ID of the environment |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/environments/1/stop"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "name": "deploy",
+  "slug": "deploy",
+  "external_url": "https://deploy.example.gitlab.com"
+}
+```
diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md
index c178e224cc5..ba953da89bc 100644
--- a/doc/api/v3_to_v4.md
+++ b/doc/api/v3_to_v4.md
@@ -30,6 +30,7 @@ changes are in V4:
 - Moved `DELETE /todos` to `POST /todos/mark_as_done` and `DELETE /todos/:todo_id` to `POST /todos/:todo_id/mark_as_done` [!9410](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9410)
 - Endpoints `/projects/owned`, `/projects/visible`, `/projects/starred` & `/projects/all` are consolidated into `/projects` using query parameters [!8962](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8962)
 - Return pagination headers for all endpoints that return an array [!8606](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8606)
+- Added `POST /environments/:environment_id/stop` to stop an environment [!8808](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8808)
 - Removed `DELETE projects/:id/deploy_keys/:key_id/disable`. Use `DELETE projects/:id/deploy_keys/:key_id` instead [!9366](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9366)
 - Moved `PUT /users/:id/(block|unblock)` to `POST /users/:id/(block|unblock)` [!9371](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9371)
 - Make subscription API more RESTful. Use `post ":project_id/:subscribable_type/:subscribable_id/subscribe"` to subscribe and `post ":project_id/:subscribable_type/:subscribable_id/unsubscribe"` to unsubscribe from a resource. [!9325](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9325)