REST API: Deprecate active/paused values in status filters

Changelog: deprecated

data/deprecations/14-8-runner-api-status-filter-does-accept-active-or-paused.yml

+- name: "REST API Runner will not accept `status` filter values of `active` or `paused`"
+  announcement_milestone: "14.8" # The milestone when this feature was first announced as deprecated.
+  announcement_date: "2022-02-22"
+  removal_milestone: "15.0" # the milestone when this feature is planned to be removed
+  removal_date: "2022-05-22" # the date of the milestone release when this feature is planned to be removed
+  breaking_change: true
+  body: | # Do not modify this line, instead modify the lines below.
+    The GitLab Runner REST endpoints will stop accepting `paused` or `active` as a status value in GitLab 15.0.
+
+    A runner's status will only relate to runner contact status, such as: `online`, `offline`.
+    Status values `paused` or `active` will no longer be accepted and will be replaced by the `paused` query parameter.
+
+    When checking for paused runners, API users are advised to specify `paused=true` as the query parameter.
+    When checking for active runners, specify `paused=false`.
+  stage: Verify
+  tiers: [Core, Premium, Ultimate]
+  issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/351109
+  documentation_url: https://docs.gitlab.com/ee/api/runners.html

doc/update/deprecations.md

@@ -733,6 +733,24 @@ The `instanceStatisticsMeasurements` GraphQL node has been renamed to `usageTren
 
 **Planned removal milestone: 15.0 (2022-05-22)**
 
+### REST API Runner will not accept `status` filter values of `active` or `paused`
+
+WARNING:
+This feature will be changed or removed in 15.0
+as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes).
+Before updating GitLab, review the details carefully to determine if you need to make any
+changes to your code, settings, or workflow.
+
+The GitLab Runner REST endpoints will stop accepting `paused` or `active` as a status value in GitLab 15.0.
+
+A runner's status will only relate to runner contact status, such as: `online`, `offline`.
+Status values `paused` or `active` will no longer be accepted and will be replaced by the `paused` query parameter.
+
+When checking for paused runners, API users are advised to specify `paused=true` as the query parameter.
+When checking for active runners, specify `paused=false`.
+
+**Planned removal milestone: 15.0 (2022-05-22)**
+
 ### REST and GraphQL API Runner usage of `active` replaced by `paused`
 
 WARNING:

lib/api/ci/runners.rb

@@ -18,6 +18,7 @@ module API
                           desc: 'The scope of specific runners to show'
           optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES,
                           desc: 'The type of the runners to show'
+          optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs'
           optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES,
                             desc: 'The status of the runners to show'
           optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show'
@@ -26,9 +27,7 @@ module API
         get do
           runners = current_user.ci_owned_runners
           runners = filter_runners(runners, params[:scope], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES)
-          runners = filter_runners(runners, params[:type], allowed_scopes: ::Ci::Runner::AVAILABLE_TYPES)
-          runners = filter_runners(runners, params[:status], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES)
-          runners = runners.tagged_with(params[:tag_list]) if params[:tag_list]
+          runners = apply_filter(runners, params)
 
           present paginate(runners), with: Entities::Ci::Runner
         end
@@ -41,6 +40,7 @@ module API
                           desc: 'The scope of specific runners to show'
           optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES,
                           desc: 'The type of the runners to show'
+          optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs'
           optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES,
                             desc: 'The status of the runners to show'
           optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show'
@@ -51,9 +51,7 @@ module API
 
           runners = ::Ci::Runner.all
           runners = filter_runners(runners, params[:scope])
-          runners = filter_runners(runners, params[:type], allowed_scopes: ::Ci::Runner::AVAILABLE_TYPES)
-          runners = filter_runners(runners, params[:status], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES)
-          runners = runners.tagged_with(params[:tag_list]) if params[:tag_list]
+          runners = apply_filter(runners, params)
 
           present paginate(runners), with: Entities::Ci::Runner
         end
@@ -163,6 +161,7 @@ module API
                           desc: 'The scope of specific runners to show'
           optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES,
                           desc: 'The type of the runners to show'
+          optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs'
           optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES,
                             desc: 'The status of the runners to show'
           optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show'
@@ -226,6 +225,7 @@ module API
         params do
           optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES,
                   desc: 'The type of the runners to show'
+          optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs'
           optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES,
                   desc: 'The status of the runners to show'
           optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show'
@@ -313,6 +313,7 @@ module API
         def apply_filter(runners, params)
           runners = filter_runners(runners, params[:type], allowed_scopes: ::Ci::Runner::AVAILABLE_TYPES)
           runners = filter_runners(runners, params[:status], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES)
+          runners = filter_runners(runners, params[:paused] ? 'paused' : 'active', allowed_scopes: %w[paused active]) if params.include?(:paused)
           runners = runners.tagged_with(params[:tag_list]) if params[:tag_list]
 
           runners

spec/requests/api/ci/runners_spec.rb

@@ -86,15 +86,25 @@ RSpec.describe API::Ci::Runners do
         expect(response).to have_gitlab_http_status(:bad_request)
       end
 
-      it 'filters runners by status' do
-        create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project])
+      context 'with an inactive runner' do
+        let_it_be(:runner) { create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project]) }
+
+        it 'filters runners by paused state' do
+          get api('/runners?paused=true', user)
+
+          expect(json_response).to match_array [
+            a_hash_including('description' => 'Inactive project runner')
+          ]
+        end
 
+        it 'filters runners by status' do
           get api('/runners?status=paused', user)
 
           expect(json_response).to match_array [
             a_hash_including('description' => 'Inactive project runner')
           ]
         end
+      end
 
       it 'does not filter by invalid status' do
         get api('/runners?status=bogus', user)
@@ -199,15 +209,25 @@ RSpec.describe API::Ci::Runners do
           expect(response).to have_gitlab_http_status(:bad_request)
         end
 
+        context 'with an inactive runner' do
+          let_it_be(:runner) { create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project]) }
+
           it 'filters runners by status' do
-          create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project])
+            get api('/runners/all?paused=true', admin)
 
+            expect(json_response).to match_array [
+              a_hash_including('description' => 'Inactive project runner')
+            ]
+          end
+
+          it 'filters runners by status' do
             get api('/runners/all?status=paused', admin)
 
             expect(json_response).to match_array [
               a_hash_including('description' => 'Inactive project runner')
             ]
           end
+        end
 
         it 'does not filter by invalid status' do
           get api('/runners/all?status=bogus', admin)
@@ -956,15 +976,25 @@ RSpec.describe API::Ci::Runners do
         expect(response).to have_gitlab_http_status(:bad_request)
       end
 
+      context 'with an inactive runner' do
+        let_it_be(:runner) { create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project]) }
+
         it 'filters runners by status' do
-        create(:ci_runner, :project, :inactive, description: 'Inactive project runner', projects: [project])
+          get api("/projects/#{project.id}/runners?paused=true", user)
 
+          expect(json_response).to match_array [
+            a_hash_including('description' => 'Inactive project runner')
+          ]
+        end
+
+        it 'filters runners by status' do
           get api("/projects/#{project.id}/runners?status=paused", user)
 
           expect(json_response).to match_array [
             a_hash_including('description' => 'Inactive project runner')
           ]
         end
+      end
 
       it 'does not filter by invalid status' do
         get api("/projects/#{project.id}/runners?status=bogus", user)
@@ -1022,10 +1052,19 @@ RSpec.describe API::Ci::Runners do
         end
       end
 
+      context 'with an inactive runner' do
+        let_it_be(:runner) { create(:ci_runner, :group, :inactive, description: 'Inactive group runner', groups: [group]) }
+
+        it 'returns runners by paused state' do
+          get api("/groups/#{group.id}/runners?paused=true", user)
+
+          expect(json_response).to match_array([
+            a_hash_including('description' => 'Inactive group runner')
+          ])
+        end
+
         context 'filter runners by status' do
           it 'returns runners by valid status' do
-          create(:ci_runner, :group, :inactive, description: 'Inactive group runner', groups: [group])
-
             get api("/groups/#{group.id}/runners?status=paused", user)
 
             expect(json_response).to match_array([
@@ -1039,6 +1078,7 @@ RSpec.describe API::Ci::Runners do
             expect(response).to have_gitlab_http_status(:bad_request)
           end
         end
+      end
 
       it 'filters runners by tag_list' do
         create(:ci_runner, :group, description: 'Runner tagged with tag1 and tag2', groups: [group], tag_list: %w[tag1 tag2])