Update API: add search param to branches

changelogs/unreleased/42712_api_branches_add_search_param_20180207.yml

+---
+title: Add search param to Branches API
+merge_request: 17005
+author: bunufi
+type: added

doc/api/branches.md

@@ -13,6 +13,7 @@ GET /projects/:id/repository/branches
 | 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 |
+| `search` | string | no | Return list of branches matching the search criteria.  |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches

lib/api/branches.rb

@@ -16,6 +16,10 @@ module API
           render_api_error!('The branch refname is invalid', 400)
         end
       end
+
+      params :filter_params do
+        optional :search, type: String, desc: 'Return list of branches matching the search criteria'
+      end
     end
 
     params do
@@ -27,15 +31,23 @@ module API
       end
       params do
         use :pagination
+        use :filter_params
       end
       get ':id/repository/branches' do
         Gitlab::QueryLimiting.whitelist('https://gitlab.com/gitlab-org/gitlab-ce/issues/42329')
 
         repository = user_project.repository
-        branches = ::Kaminari.paginate_array(repository.branches.sort_by(&:name))
+
+        branches = BranchesFinder.new(repository, declared_params(include_missing: false)).execute
+
         merged_branch_names = repository.merged_branch_names(branches.map(&:name))
 
-        present paginate(branches), with: Entities::Branch, project: user_project, merged_branch_names: merged_branch_names
+        present(
+          paginate(::Kaminari.paginate_array(branches)),
+          with: Entities::Branch,
+          project: user_project,
+          merged_branch_names: merged_branch_names
+        )
       end
 
       resource ':id/repository/branches/:branch', requirements: BRANCH_ENDPOINT_REQUIREMENTS do

spec/requests/api/branches_spec.rb

@@ -39,6 +39,27 @@ describe API::Branches do
       end
     end
 
+    context 'when search parameter is passed' do
+      context 'and branch exists' do
+        it 'returns correct branches' do
+          get api(route, user), per_page: 100, search: branch_name
+
+          searched_branch_names = json_response.map { |branch| branch['name'] }
+          project_branch_names = project.repository.branch_names.grep(/#{branch_name}/)
+
+          expect(searched_branch_names).to match_array(project_branch_names)
+        end
+      end
+
+      context 'and branch does not exist' do
+        it 'returns an empty array' do
+          get api(route, user), per_page: 100, search: 'no_such_branch_name_entropy_of_jabadabadu'
+
+          expect(json_response).to eq []
+        end
+      end
+    end
+
     context 'when unauthenticated', 'and project is public' do
       before do
         project.update(visibility_level: Gitlab::VisibilityLevel::PUBLIC)