Add `due_date` param to Issues REST API

Adds a `due_date` param that already exists in our IssuesFinder and
accepts values such as `0`, `overdue`, `week`, `month`, and
`next_month_and_previous_two_weeks`. Returns issues whose due_date fit
these descriptions.

changelogs/unreleased/233420-add_due_date_to_issues_rest_api.yml

+---
+title: Add due_date filter param to Issues REST API
+merge_request: 38973
+author:
+type: added

doc/api/issues.md

@@ -72,6 +72,7 @@ GET /issues?confidential=true
 | `confidential`      | boolean          | no         | Filter confidential or public issues.                                                                                                               |
 | `not`               | Hash             | no         | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji` |
 | `non_archived`      | boolean          | no         | Return issues only from non-archived projects. If `false`, response will return issues from both archived and non-archived projects. Default is `true`. _(Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/197170))_ |
+| `due_date`          | string           | no         | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues"
@@ -231,6 +232,7 @@ GET /groups/:id/issues?confidential=true
 | `confidential`     | boolean          | no         | Filter confidential or public issues.                                                                                         |
 | `not`               | Hash             | no         | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` |
 | `non_archived`      | boolean          | no         | Return issues from non archived projects. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785))_ |
+| `due_date`          | string           | no         | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues"
@@ -388,6 +390,7 @@ GET /projects/:id/issues?confidential=true
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                             |
 | `confidential`     | boolean          | no         | Filter confidential or public issues.                                                                                         |
 | `not`               | Hash             | no         | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` |
+| `due_date`          | string           | no         | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues"

lib/api/issues.rb

@@ -55,6 +55,8 @@ module API
                  desc: 'Return issues ordered by `created_at` or `updated_at` fields.'
         optional :sort, type: String, values: %w[asc desc], default: 'desc',
                  desc: 'Return issues sorted in `asc` or `desc` order.'
+        optional :due_date, type: String, values: %w[0 overdue week month next_month_and_previous_two_weeks],
+                 desc: 'Return issues that have no due date (`0`), or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`, `0`'
 
         use :issues_stats_params
         use :pagination

spec/requests/api/issues/issues_spec.rb

@@ -387,6 +387,54 @@ RSpec.describe API::Issues do
         end
       end
 
+      context 'filtering by due date' do
+        # This date chosen because it is the beginning of a week + near the beginning of a month
+        let_it_be(:frozen_time) { DateTime.parse('2020-08-03 12:00') }
+
+        let_it_be(:issue2) { create(:issue, project: project, author: user, due_date: frozen_time + 3.days) }
+        let_it_be(:issue3) { create(:issue, project: project, author: user, due_date: frozen_time + 10.days) }
+        let_it_be(:issue4) { create(:issue, project: project, author: user, due_date: frozen_time + 34.days) }
+        let_it_be(:issue5) { create(:issue, project: project, author: user, due_date: frozen_time - 8.days) }
+
+        before do
+          travel_to(frozen_time)
+        end
+
+        after do
+          travel_back
+        end
+
+        it 'returns issues without due date' do
+          get api('/issues?due_date=0', user)
+
+          expect_paginated_array_response(issue.id, closed_issue.id)
+        end
+
+        it 'returns issues due for this week' do
+          get api('/issues?due_date=week', user)
+
+          expect_paginated_array_response(issue2.id)
+        end
+
+        it 'returns issues due for this month' do
+          get api('/issues?due_date=month', user)
+
+          expect_paginated_array_response(issue3.id, issue2.id)
+        end
+
+        it 'returns issues that are due previous two weeks and next month' do
+          get api('/issues?due_date=next_month_and_previous_two_weeks', user)
+
+          expect_paginated_array_response(issue5.id, issue4.id, issue3.id, issue2.id)
+        end
+
+        it 'returns issues that are overdue' do
+          get api('/issues?due_date=overdue', user)
+
+          expect_paginated_array_response(issue5.id)
+        end
+      end
+
       context 'filter by labels or label_name param' do
         context 'N+1' do
           let(:label_b) { create(:label, title: 'foo', project: project) }