Add filters for created/updated at to Epics API

When trying to retrieve data from a specific range of time, filtering
by created and updated time prevents the client from needing to scan
the entire data set.

The Epics API can now, consistent with the Issues API, be filtered by:
- created_after
- created_before
- updated_after
- updated_before

doc/api/epics.md

@@ -36,15 +36,19 @@ GET /groups/:id/epics?labels=bug,reproduced
 GET /groups/:id/epics?state=opened
 ```
 
-| Attribute           | Type             | Required   | Description                                                                            |
-| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user                |
-| `author_id`         | integer          | no         | Return epics created by the given user `id`                                                                                                        |
-| `labels`            | string           | no         | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used                |
-| `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`                                                 |
+| Attribute           | Type             | Required   | Description                                                                                                                 |
+| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user               |
+| `author_id`         | integer          | no         | Return epics created by the given user `id`                                                                                 |
+| `labels`            | string           | no         | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used |
+| `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`                          |
+| `created_after`     | datetime         | no         | Return epics created on or after the given time                                                                             |
+| `created_before`    | datetime         | no         | Return epics created on or before the given time                                                                            |
+| `updated_after`     | datetime         | no         | Return epics updated on or after the given time                                                                             |
+| `updated_before`    | datetime         | no         | Return epics updated on or before the given time                                                                            |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics

ee/app/finders/epics_finder.rb

@@ -26,6 +26,7 @@ class EpicsFinder < IssuableFinder
 
     items = init_collection
     items = by_created_at(items)
+    items = by_updated_at(items)
     items = by_search(items)
     items = by_author(items)
     items = by_timeframe(items)

ee/changelogs/unreleased/jramsay-filter-epics.yml

+---
+title: Add created_at and updated_at filters to Epics API
+merge_request: 11315
+author: jramsay
+type: added

ee/lib/api/epics.rb

@@ -30,6 +30,10 @@ module API
                          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: Array[String], coerce_with: Validations::Types::LabelsList.coerce, desc: 'Comma-separated list of label names'
+        optional :created_after, type: DateTime, desc: 'Return epics created after the specified time'
+        optional :created_before, type: DateTime, desc: 'Return epics created before the specified time'
+        optional :updated_after, type: DateTime, desc: 'Return epics updated after the specified time'
+        optional :updated_before, type: DateTime, desc: 'Return epics updated before the specified time'
         use :pagination
       end
       get ':id/(-/)epics' do

ee/spec/requests/api/epics_spec.rb

@@ -308,6 +308,46 @@ describe API::Epics do
       it_behaves_like 'can admin epics'
     end
 
+    context 'filtering before a specific date' do
+      let!(:epic) { create(:epic, group: group, created_at: Date.new(2000, 1, 1), updated_at: Date.new(2000, 1, 1)) }
+
+      before do
+        stub_licensed_features(epics: true)
+      end
+
+      it 'returns epics created before a specific date' do
+        get api(url, user), params: { created_before: '2000-01-02T00:00:00.060Z' }
+
+        expect_paginated_array_response(epic.id)
+      end
+
+      it 'returns epics updated before a specific date' do
+        get api(url, user), params: { updated_before: '2000-01-02T00:00:00.060Z' }
+
+        expect_paginated_array_response(epic.id)
+      end
+    end
+
+    context 'filtering after a specific date' do
+      let!(:epic) { create(:epic, group: group, created_at: 1.week.from_now, updated_at: 1.week.from_now) }
+
+      before do
+        stub_licensed_features(epics: true)
+      end
+
+      it 'returns epics created after a specific date' do
+        get api(url, user), params: { created_after: epic.created_at }
+
+        expect_paginated_array_response(epic.id)
+      end
+
+      it 'returns epics updated after a specific date' do
+        get api(url, user), params: { updated_after: epic.updated_at }
+
+        expect_paginated_array_response(epic.id)
+      end
+    end
+
     context 'with pagination params' do
       let(:page) { 1 }
       let(:per_page) { 2 }