Merge branch '7615-api-status-filter' into 'master'

Filter epics by state in API

Closes #7615

See merge request gitlab-org/gitlab-ee!8179

doc/api/epics.md

@@ -26,6 +26,7 @@ Gets all epics of the requested group and its subgroups.
 GET /groups/:id/epics
 GET /groups/:id/epics?author_id=5
 GET /groups/:id/epics?labels=bug,reproduced
+GET /groups/:id/epics?state=opened
 ```
 
 | Attribute           | Type             | Required   | Description                                                                            |
@@ -36,6 +37,7 @@ GET /groups/:id/epics?labels=bug,reproduced
 | `order_by`          | string           | no         | Return epics ordered by `created_at` or `updated_at` fields. Default is `created_at`                                                               |
 | `sort`              | string           | no         | Return epics sorted in `asc` or `desc` order. Default is `desc`                                                                                    |
 | `search`            | string           | no         | Search epics against their `title` and `description`                                                                                               |
+| `state`             | string           | no         | Search epics against their `state`, possible filters: `opened`, `closed` and `all`, default: `all`                                                 |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/epics

ee/changelogs/unreleased/7615-api-status-filter.yml

+---
+title: Filter epics by state in API
+merge_request: 8179
+author:
+type: added

ee/lib/api/epics.rb

@@ -58,6 +58,8 @@ module API
         optional :sort, type: String, values: %w[asc desc], default: 'desc',
                         desc: 'Return epics sorted in `asc` or `desc` order.'
         optional :search, type: String, desc: 'Search epics for text present in the title or description'
+        optional :state, type: String, values: %w[opened closed all], default: 'all',
+                         desc: 'Return opened, closed, or all epics'
         optional :author_id, type: Integer, desc: 'Return epics which are authored by the user with the given ID'
         optional :labels, type: String, desc: 'Comma-separated list of label names'
       end

ee/spec/requests/api/epics_spec.rb

@@ -92,6 +92,7 @@ describe API::Epics do
       let!(:epic) do
         create(:epic,
                group: group,
+               state: :closed,
                created_at: 3.days.ago,
                updated_at: 2.days.ago)
       end
@@ -135,6 +136,18 @@ describe API::Epics do
         expect_array_response([epic2.id])
       end
 
+      it 'returns epics matching given status' do
+        get api(url, user), state: :opened
+
+        expect_array_response([epic2.id])
+      end
+
+      it 'returns all epics when state set to all' do
+        get api(url, user), state: :all
+
+        expect_array_response([epic2.id, epic.id])
+      end
+
       it 'sorts by created_at descending by default' do
         get api(url, user)