Add name & search parameters to project environments API

app/finders/environments_finder.rb

@@ -47,6 +47,19 @@ class EnvironmentsFinder
   end
   # rubocop: enable CodeReuse/ActiveRecord
 
+  # This method will eventually take the place of `#execute` as an
+  # efficient way to get relevant environment entries.
+  # Currently, `#execute` method has a serious technical debt and
+  # we will likely rework on it in the future.
+  # See more https://gitlab.com/gitlab-org/gitlab-ce/issues/63381
+  def find
+    environments = project.environments
+    environments = by_name(environments)
+    environments = by_search(environments)
+
+    environments
+  end
+
   private
 
   def ref
@@ -56,4 +69,20 @@ class EnvironmentsFinder
   def commit
     params[:commit]
   end
+
+  def by_name(environments)
+    if params[:name].present?
+      environments.for_name(params[:name])
+    else
+      environments
+    end
+  end
+
+  def by_search(environments)
+    if params[:search].present?
+      environments.for_name_like(params[:search], limit: nil)
+    else
+      environments
+    end
+  end
 end

changelogs/add-name-parameter-to-project-environments-api.yml

+---
+title: Add `name` and `search` parameters to project environments API
+merge_request: 29385
+author: Lee Tickett
+type: added

doc/api/environments.md

@@ -11,9 +11,11 @@ GET /projects/:id/environments
 | Attribute | Type    | Required | Description           |
 | --------- | ------- | -------- | --------------------- |
 | `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name`    | string  | no       | Return the environment with this name. Mutually exclusive with `search` |
+| `search`  | string  | no       | Return list of environments matching the search criteria. Mutually exclusive with `name` |
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/environments
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo
 ```
 
 Example response:

lib/api/environments.rb

@@ -18,11 +18,16 @@ module API
       end
       params do
         use :pagination
+        optional :name, type: String, desc: 'Returns the environment with this name'
+        optional :search, type: String, desc: 'Returns list of environments matching the search criteria'
+        mutually_exclusive :name, :search, message: 'cannot be used together'
       end
       get ':id/environments' do
         authorize! :read_environment, user_project
 
-        present paginate(user_project.environments), with: Entities::Environment, current_user: current_user
+        environments = ::EnvironmentsFinder.new(user_project, current_user, params).find
+
+        present paginate(environments), with: Entities::Environment, current_user: current_user
       end
 
       desc 'Creates a new environment' do

spec/requests/api/environments_spec.rb

@@ -34,6 +34,47 @@ describe API::Environments do
         expect(json_response.first['project'].keys).to contain_exactly(*project_data_keys)
         expect(json_response.first).not_to have_key("last_deployment")
       end
+
+      context 'when filtering' do
+        let!(:environment2) { create(:environment, project: project) }
+
+        it 'returns environment by name' do
+          get api("/projects/#{project.id}/environments?name=#{environment.name}", user)
+
+          expect(response).to have_gitlab_http_status(200)
+          expect(response).to include_pagination_headers
+          expect(json_response).to be_an Array
+          expect(json_response.size).to eq(1)
+          expect(json_response.first['name']).to eq(environment.name)
+        end
+
+        it 'returns no environment by non-existent name' do
+          get api("/projects/#{project.id}/environments?name=test", user)
+
+          expect(response).to have_gitlab_http_status(200)
+          expect(response).to include_pagination_headers
+          expect(json_response).to be_an Array
+          expect(json_response.size).to eq(0)
+        end
+
+        it 'returns environments by name_like' do
+          get api("/projects/#{project.id}/environments?search=envir", user)
+
+          expect(response).to have_gitlab_http_status(200)
+          expect(response).to include_pagination_headers
+          expect(json_response).to be_an Array
+          expect(json_response.size).to eq(2)
+        end
+
+        it 'returns no environment by non-existent name_like' do
+          get api("/projects/#{project.id}/environments?search=test", user)
+
+          expect(response).to have_gitlab_http_status(200)
+          expect(response).to include_pagination_headers
+          expect(json_response).to be_an Array
+          expect(json_response.size).to eq(0)
+        end
+      end
     end
 
     context 'as non member' do