Add create user starred dashboard API endpoint

To make starring dashboard available we need to introduce new API
endpoint which will recieve POST requests and add corresponding
database entries.

changelogs/unreleased/mwaw-214581-star-metrics-dashboard-endpoint.yml

+---
+title: New API endpoint for starring metrics dashboards
+merge_request: 31316
+author:
+type: added

doc/api/api_resources.md

@@ -72,6 +72,7 @@ The following API resources are available in the project context:
 | [Search](search.md)                                                 | `/projects/:id/search` (also available for groups and standalone)                                                                                                                                     |
 | [Services](services.md)                                             | `/projects/:id/services`                                                                                                                                                                              |
 | [Tags](tags.md)                                                     | `/projects/:id/repository/tags`                                                                                                                                                                       |
+| [User-starred metrics dashboards](metrics_user_starred_dashboards.md ) | `/projects/:id/metrics/user_starred_dashboards`                                                                                                                             |
 | [Visual Review discussions](visual_review_discussions.md) **(STARTER)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions`                                                                                                                        |
 | [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)**                | `/vulnerabilities/:id`                                                                                                                                                                       |
 | [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE)**    | `/projects/:id/vulnerability_exports`                                                                                                                                                                       |

doc/api/metrics_user_starred_dashboards.md

+# User-starred metrics dashboards API
+
+The starred dashboard feature makes navigating to frequently-used dashboards easier
+by displaying favorited dashboards at the top of the select list.
+
+## Add a star to a dashboard
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31316) in GitLab 13.0.
+
+```plaintext
+POST /projects/:id/metrics/user_starred_dashboards
+```
+
+Parameters:
+
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `dashboard_path` | string        | yes      | URL-encoded path to file defining the dashboard which should be marked as favorite.   |
+
+```shell
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \
+ --data-urlencode "dashboard_path=config/prometheus/dashboards/common_metrics.yml"
+```
+
+Example Response:
+
+```json
+{
+  "id": 5,
+  "dashboard_path": "config/prometheus/common_metrics.yml",
+  "user_id": 1,
+  "project_id": 20
+}
+```

doc/user/permissions.md

@@ -70,6 +70,7 @@ The following table depicts the various user permission levels in a project.
 | View confidential issues                          | (*2*)   | ✓          | ✓           | ✓        | ✓      |
 | View [Releases](project/releases/index.md)        | ✓ (*6*) | ✓          | ✓           | ✓        | ✓      |
 | View requirements **(ULTIMATE)**                  | ✓       | ✓          | ✓           | ✓        | ✓      |
+| Manage user-starred metrics dashboards (*7*)      | ✓       | ✓          | ✓           | ✓        | ✓      |
 | Assign issues                                     |         | ✓          | ✓           | ✓        | ✓      |
 | Label issues                                      |         | ✓          | ✓           | ✓        | ✓      |
 | Set issue weight                                  |         | ✓          | ✓           | ✓        | ✓      |
@@ -170,6 +171,7 @@ The following table depicts the various user permission levels in a project.
 1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](./project/protected_branches.md).
 1. If the [branch is protected](./project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given.
 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits.
+1. Actions are limited only to records owned (referenced) by user.
 
 ## Project features permissions
 

lib/api/api.rb

@@ -162,6 +162,7 @@ module API
       mount ::API::MergeRequestDiffs
       mount ::API::MergeRequests
       mount ::API::Metrics::Dashboard::Annotations
+      mount ::API::Metrics::UserStarredDashboards
       mount ::API::Namespaces
       mount ::API::Notes
       mount ::API::Discussions

lib/api/entities/metrics/user_starred_dashboard.rb

+# frozen_string_literal: true
+
+module API
+  module Entities
+    module Metrics
+      class UserStarredDashboard < Grape::Entity
+        expose :id, :dashboard_path, :user_id, :project_id
+      end
+    end
+  end
+end

lib/api/metrics/user_starred_dashboards.rb

+# frozen_string_literal: true
+
+module API
+  module Metrics
+    class UserStarredDashboards < Grape::API
+      desc 'Marks selected metrics dashboard as starred' do
+        success Entities::Metrics::UserStarredDashboard
+      end
+
+      params do
+        requires :dashboard_path, type: String, allow_blank: false, coerce_with: ->(val) { CGI.unescape(val) },
+                 desc: 'Url encoded path to a file defining the dashboard to which the star should be added'
+      end
+
+      resource :projects do
+        post ':id/metrics/user_starred_dashboards' do
+          result = ::Metrics::UsersStarredDashboards::CreateService.new(current_user, user_project, params[:dashboard_path]).execute
+
+          if result.success?
+            present result.payload, with: Entities::Metrics::UserStarredDashboard
+          else
+            error!({ errors: result.message }, 400)
+          end
+        end
+      end
+    end
+  end
+end

spec/requests/api/metrics/user_starred_dashboards_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe API::Metrics::UserStarredDashboards do
+  let_it_be(:user) { create(:user) }
+  let!(:project) { create(:project, :private, :repository, :custom_repo, namespace: user.namespace, files: { dashboard => dashboard_yml }) }
+  let(:dashboard_yml) { fixture_file('lib/gitlab/metrics/dashboard/sample_dashboard.yml') }
+  let(:dashboard) { '.gitlab/dashboards/find&seek.yml' }
+  let(:params) do
+    {
+      user: user,
+      project: project,
+      dashboard_path: CGI.escape(dashboard)
+    }
+  end
+
+  describe 'POST /projects/:id/metrics/user_starred_dashboards' do
+    let(:url) { "/projects/#{project.id}/metrics/user_starred_dashboards" }
+
+    before do
+      project.add_reporter(user)
+    end
+
+    context 'with correct permissions' do
+      context 'with valid parameters' do
+        context 'dashboard_path as url param url escaped' do
+          it 'creates a new annotation', :aggregate_failures do
+            post api(url, user), params: params
+
+            expect(response).to have_gitlab_http_status(:created)
+            expect(json_response['project_id']).to eq(project.id)
+            expect(json_response['user_id']).to eq(user.id)
+            expect(json_response['dashboard_path']).to eq(dashboard)
+          end
+        end
+
+        context 'dashboard_path in request body unescaped' do
+          let(:params) do
+            {
+              user: user,
+              project: project,
+              dashboard_path: dashboard
+            }
+          end
+
+          it 'creates a new annotation', :aggregate_failures do
+            post api(url, user), params: params
+
+            expect(response).to have_gitlab_http_status(:created)
+            expect(json_response['project_id']).to eq(project.id)
+            expect(json_response['user_id']).to eq(user.id)
+            expect(json_response['dashboard_path']).to eq(dashboard)
+          end
+        end
+      end
+
+      context 'with invalid parameters' do
+        it 'returns error message' do
+          post api(url, user), params: { dashboard_path: '' }
+
+          expect(response).to have_gitlab_http_status(:bad_request)
+          expect(json_response['error']).to eq('dashboard_path is empty')
+        end
+
+        context 'user is missing' do
+          it 'returns 404 not found' do
+            post api(url, nil), params: params
+
+            expect(response).to have_gitlab_http_status(:not_found)
+          end
+        end
+
+        context 'project is missing' do
+          it 'returns 404 not found' do
+            post api("/projects/#{project.id + 1}/user_starred_dashboards", user), params: params
+
+            expect(response).to have_gitlab_http_status(:not_found)
+          end
+        end
+      end
+    end
+
+    context 'without correct permissions' do
+      it 'returns 404 not found' do
+        post api(url, create(:user)), params: params
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+    end
+  end
+end