Merge branch '323548-move-definitions-endpoint-docs-to-api-resources' into 'master'

Move metric definitions API endpoint docs to UsageData API resources page

See merge request gitlab-org/gitlab!59050

doc/api/api_resources.md

@@ -167,7 +167,8 @@ The following API resources are available outside of project and group contexts
 | [Sidekiq metrics](sidekiq_metrics.md) **(FREE SELF)** | `/sidekiq`                                                           |
 | [Suggestions](suggestions.md)                      | `/suggestions`                                                          |
 | [System hooks](system_hooks.md)                    | `/hooks`                                                                |
-| [To-dos](todos.md)                                  | `/todos`                                                                |
+| [To-dos](todos.md)                                 | `/todos`                                                                |
+| [Usage data](usage_data.md)                        | `/usage_data` (For GitLab instance [Administrator](../user/permissions.md) users only) |
 | [Users](users.md)                                  | `/users`                                                                |
 | [Validate `.gitlab-ci.yml` file](lint.md)          | `/lint`                                                                 |
 | [Version](version.md)                              | `/version`                                                              |

doc/api/usage_data.md

@@ -5,17 +5,61 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference, api
 ---
 
-# UsageData API **(FREE SELF)**
+# Usage Data API **(FREE SELF)**
 
-The UsageData API, associated with [Usage Ping](../development/usage_ping/index.md), is available only for
-the use of GitLab instance [Administrator](../user/permissions.md) users.
+The Usage Data API is associated with [Usage Ping](../development/usage_ping/index.md).
 
-## UsageDataQueries API
+## Export metric definitions as a single YAML file
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11.
+
+Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](../development/usage_ping/dictionary.md), for easier importing.
+
+```plaintext
+GET /usage_data/metric_definitions
+```
+
+Example request:
+
+```shell
+curl "https://gitlab.example.com/api/v4/usage_data/metric_definitions"
+```
+
+Example response:
+
+```yaml
+---
+- key_path: redis_hll_counters.search.i_search_paid_monthly
+  description: Calculated unique users to perform a search with a paid license enabled
+    by month
+  product_section: enablement
+  product_stage: enablement
+  product_group: group::global search
+  product_category: global_search
+  value_type: number
+  status: data_available
+  time_frame: 28d
+  data_source: redis_hll
+  distribution:
+  - ee
+  tier:
+  - premium
+  - ultimate
+...
+```
+
+## Export Usage Ping SQL queries
+
+This action is available only for the GitLab instance [Administrator](../user/permissions.md) users.
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57016) in GitLab 13.11.
 > - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default.
 
-Return all of the raw SQL queries used to compute usage ping.
+Return all of the raw SQL queries used to compute Usage Ping.
+
+```plaintext
+GET /usage_data/queries
+```
 
 Example request:
 
@@ -23,7 +67,7 @@ Example request:
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/usage_data/queries"
 ```
 
-Sample response
+Example response:
 
 ```json
 {

doc/development/usage_ping/index.md

@@ -1411,37 +1411,6 @@ bin/rake gitlab:usage_data:dump_sql_in_json
 bin/rake gitlab:usage_data:dump_sql_in_yaml > ~/Desktop/usage-metrics-2020-09-02.yaml
 ```
 
-## Export metric definitions as a single YAML file
-
-Use this API endpoint to export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](dictionary.md), for easier importing.
-
-```plaintext
-GET /usage_data/metric_definitions
-```
-
-Response
-
-```yaml
----
-- key_path: redis_hll_counters.search.i_search_paid_monthly
-  description: Calculated unique users to perform a search with a paid license enabled
-    by month
-  product_section: enablement
-  product_stage: enablement
-  product_group: group::global search
-  product_category: global_search
-  value_type: number
-  status: data_available
-  time_frame: 28d
-  data_source: redis_hll
-  distribution:
-  - ee
-  tier:
-  - premium
-  - ultimate
-...
-```
-
 ## Generating and troubleshooting usage ping
 
 This activity is to be done via a detached screen session on a remote server.