Add environment `/stop` action

Add endpoint to stop an environment through the API.

changelogs/unreleased/27142-api-replace-destroy-with-stop-environment.yml

+---
+title: API: Add environment stop action
+merge_request: 8808
+author:

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"
+}
+```

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)

lib/api/environments.rb

@@ -81,6 +81,23 @@ module API
 
         environment.destroy
       end
+
+      desc 'Stops an existing environment' do
+        success Entities::Environment
+      end
+      params do
+        requires :environment_id, type: Integer,  desc: 'The environment ID'
+      end
+      post ':id/environments/:environment_id/stop' do
+        authorize! :create_deployment, user_project
+
+        environment = user_project.environments.find(params[:environment_id])
+
+        environment.stop_with_action!(current_user)
+
+        status 200
+        present environment, with: Entities::Environment
+      end
     end
   end
 end

spec/requests/api/environments_spec.rb

@@ -141,4 +141,39 @@ describe API::Environments, api: true  do
       end
     end
   end
+
+  describe 'POST /projects/:id/environments/:environment_id/stop' do
+    context 'as a master' do
+      context 'with a stoppable environment' do
+        before do
+          environment.update(state: :available)
+
+          post api("/projects/#{project.id}/environments/#{environment.id}/stop", user)
+        end
+
+        it 'returns a 200' do
+          expect(response).to have_http_status(200)
+        end
+
+        it 'actually stops the environment' do
+          expect(environment.reload).to be_stopped
+        end
+      end
+
+      it 'returns a 404 for non existing id' do
+        post api("/projects/#{project.id}/environments/12345/stop", user)
+
+        expect(response).to have_http_status(404)
+        expect(json_response['message']).to eq('404 Not found')
+      end
+    end
+
+    context 'a non member' do
+      it 'rejects the request' do
+        post api("/projects/#{project.id}/environments/#{environment.id}/stop", non_member)
+
+        expect(response).to have_http_status(404)
+      end
+    end
+  end
 end