PMM-12258 fix github API documentation workflow (#2518)

* PMM-12258 add the first category * PMM-12258 refactor and fix the documentation files * PMM-12258 add an empty line * PMM-12258 rename the file --------- Co-authored-by: Alex Tymchuk <[email protected]>
percona · Oct 4, 2023 · e090d0f · e090d0f
1 parent 4d49b16
commit e090d0f
Show file tree

Hide file tree

Showing 29 changed files with 303 additions and 154 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -6,6 +6,7 @@ on:
     paths:
       - "api/**"
       - "docs/api/**"
+
   workflow_dispatch:
     inputs:
       version:

diff --git a/docs/api/access-control.md → docs/api/access-control/access-control.md b/docs/api/access-control.md → docs/api/access-control/access-control.md
@@ -1,11 +1,13 @@
 ---
-slug: 'access-control'
+title: Access Control
+slug: access-control
+category: 64e49e26498dc6002b62ebf4
 ---
 
 ## Overview
 
 Access Control in PMM can be used to restrict access to individual metrics.  
-Access Control is in tech preview and needs to be enabled manually from the PMM settings before it can be used.
+Access Control is in **tech preview** and needs to be enabled manually from PMM settings before it can be used.
 
 Once enabled, restricting access to metrics can be performed by:
 
@@ -14,12 +16,12 @@ Once enabled, restricting access to metrics can be performed by:
 
 ### Create a Percona role
 
-```bash
-curl -X POST "http://localhost/v1/management/Role/Create" \ 
+```shell
+curl -X POST "http://localhost/v1/management/Role/Create" \
      -H "Authorization: Basic xxx" \
-     -H "Content-Type: application/json" \ 
+     -H "Content-Type: application/json" \
      -d '{
-        "title": "My custom role role",
+        "title": "My custom role",
         "filter": "{environment=\"staging\"}"
       }'
 ```
@@ -32,10 +34,10 @@ Full access can be provided by specifying an empty `filter` field.
 Users can be assigned roles by using the `/v1/management/Role/Assign` API.  
 The endpoint assigns new roles to a user. Other roles, that may have been assigned to the user previously, stay intact.
 
-```bash
-curl -X POST "http://localhost/v1/management/Role/Assign" \ 
+```shell
+curl -X POST "http://localhost/v1/management/Role/Assign" \
      -H "Authorization: Basic xxx" \
-     -H "Content-Type: application/json" \ 
+     -H "Content-Type: application/json" \
      -d '{
         "user_id": 1,
         "role_ids": [2, 3, 4]

diff --git a/docs/api/adhoc-backup.md b/docs/api/adhoc-backup.md
diff --git a/docs/api/advisor-api/advisors-and-advisor-checks.md b/docs/api/advisor-api/advisors-and-advisor-checks.md
@@ -0,0 +1,7 @@
+---
+title: Percona Advisors and Advisors checks
+slug: advisors-and-advisor-checks
+category: 6291050b9400a1001ae1877d
+order: 2
+hidden: 0
+---
diff --git a/docs/api/advisor-api/changing-advisor-checks.md b/docs/api/advisor-api/changing-advisor-checks.md
@@ -0,0 +1,7 @@
+---
+title: Changing Advisors and Advisor checks
+slug: changing-advisor-checks
+category: 6291050b9400a1001ae1877d
+order: 3
+hidden: 0
+---
diff --git a/docs/api/advisor-api/failed-checks.md b/docs/api/advisor-api/failed-checks.md
@@ -0,0 +1,7 @@
+---
+title: List of problems detected by Advisors
+slug: failed-checks
+category: 6291050b9400a1001ae1877d
+order: 1
+hidden: 0
+---
diff --git a/docs/api/advisor-api/overview.md b/docs/api/advisor-api/overview.md
@@ -0,0 +1,15 @@
+---
+title: Overview
+slug: percona-advisors
+category: 6291050b9400a1001ae1877d
+order: 0
+---
+
+
+This section is about API for managing Percona [Advisors](https://docs.percona.com/percona-monitoring-and-management/get-started/advisors.html), and [Advisors Checks](https://docs.percona.com/percona-monitoring-and-management/details/develop-checks/index.html).
+
+This section has three main subsections.
+
+- In [List of problems detected by Advisors](reference/failed-checks) you can find API to get information about potential problems with your Infrastructure detected by Advisors.
+- [Percona Advisors and Advisors checks](reference/advisors-and-advisor-checks) lists all Advisors and Advisor Checks available in your PMM.
+- [Changing Advisors and Advisor checks](reference/changing-advisor-checks) will help you automate Advisor checks modification if needed.
diff --git a/docs/api/backups/list-locations.md b/docs/api/backups/list-locations.md
@@ -0,0 +1,20 @@
+---
+title: List Locations
+slug: listlocations
+excerpt: ListLocations returns a list of all backup locations.
+category: 626badcabbc59c02acc1a540
+---
+
+The following API call will list all the available backup locations:
+
+```shell
+curl --insecure -X POST \
+  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
+	-H 'Accept: application/json' \
+	-H 'Content-Type: application/json' \
+  --url https://127.0.0.1/v1/management/backup/Locations/List \
+```
+
+Please note that locations are good for storing any type of backup disregarding the technology or the database vendor. However, for a better organization of your file system storage, you'll probably want to create different locations based on a certain criteria. For example, it can be a department, a region, etc.
+
+You will need the [authetication token](ref:authentication).
diff --git a/docs/api/backups/restore-backup.md b/docs/api/backups/restore-backup.md
@@ -0,0 +1,44 @@
+---
+title: Restore from a backup
+slug: restorebackup
+excerpt: This endpoint allows to restore a database from a previously made backup.
+category: 626badcabbc59c02acc1a540
+order: 1
+---
+
+PMM can backup the monitored services.
+
+This section describes making ad-hoc backups from a service.
+
+### Restoring From a Backup
+
+Here is an example of an API call to restore from a backup:
+
+```shell
+curl --insecure -X POST -H 'Authorization: Bearer XXXXX' \
+     --request POST \
+     --url https://127.0.0.1/v1/management/backup/Backups/Restore \
+     --header 'Accept: application/json' \
+     --header 'Content-Type: application/json' \
+     --data '
+{
+     "service_id": "/service_id/XXXXX",
+     "artifact_id": "/location_id/XXXXX",
+     "pitr_timestamp": "2023-09-09T10:02:25.998"
+}
+'
+```
+
+You require an authentication token, which is described [here](ref:authentication).
+
+Also, you require the [service_id](ref:listservices) and [location_id](ref:listlocations).
+
+You can defined a `name` and a `description` for each backup. You can also configure `retry_interval` and `retries` if required.
+
+### Error messages
+
+The API call could return an error message in the details, containing a specific ErrorCode indicating the failure reason:
+- ERROR_CODE_XTRABACKUP_NOT_INSTALLED - xtrabackup is not installed on the service
+- ERROR_CODE_INVALID_XTRABACKUP - different versions of xtrabackup and xbcloud
+- ERROR_CODE_INCOMPATIBLE_XTRABACKUP - xtrabackup is not compatible with MySQL for making a backup
+- ERROR_CODE_INCOMPATIBLE_TARGET_MYSQL - target MySQL version is not compatible with the artifact to perform a restore of the backup
diff --git a/docs/api/backups/start-backup.md b/docs/api/backups/start-backup.md
@@ -0,0 +1,46 @@
+---
+title: Make a backup
+slug: startbackup
+excerpt: This endpoint allows to make an unscheduled, or ad-hoc, backup of a given service.
+category: 626badcabbc59c02acc1a540
+order: 0
+---
+
+PMM can backup the monitored services.
+
+This section describes how to make an ad-hoc backup of a service.
+
+### Creating a Backup
+
+Here is an example of an API call to create a backup:
+
+```shell
+curl --insecure -X POST -H 'Authorization: Bearer XXXXX' \
+     --request POST \
+     --url https://127.0.0.1/v1/management/backup/Backups/Start \
+     --header 'Accept: application/json' \
+     --header 'Content-Type: application/json' \
+     --data '
+{
+     "service_id": "/service_id/XXXXX",
+     "location_id": "/location_id/XXXXX",
+     "name": "Test Backup",
+     "description": "Test Backup",
+     "retry_interval": "60s",
+     "retries": 1
+}
+'
+```
+
+You require an authentication token, which is described [here](ref:authentication).
+
+Also, you require the [service_id](ref:listservices) and [location_id](ref:listlocations).
+
+You can defined a `name` and a `description` for each backup. You can also configure `retry_interval` and `retries` if required.
+
+### Error messages
+
+The API call could return an error message in the details, containing a specific ErrorCode indicating the failure reason:
+- ERROR_CODE_XTRABACKUP_NOT_INSTALLED - xtrabackup is not installed on the service
+- ERROR_CODE_INVALID_XTRABACKUP - different versions of xtrabackup and xbcloud
+- ERROR_CODE_INCOMPATIBLE_XTRABACKUP - xtrabackup is not compatible with MySQL to make a backup
diff --git a/docs/api/createpsmdbcluster.md → docs/api/dbaas/create-psmdb-cluster.md b/docs/api/createpsmdbcluster.md → docs/api/dbaas/create-psmdb-cluster.md
@@ -1,6 +1,12 @@
-### Create a PSMDB Cluster
+---
+title: Create a PSMDB Cluster
+slug: create-psmdb-cluster
+category: 651c00ce1679590036133c8c
+order: 2
+hidden: 0
+---
 
-The PSMDB Create endpoint receives this structure:
+The PSMDB Create endpoint receives this structure of:
 
 ```json
 {
@@ -21,7 +27,7 @@ The PSMDB Create endpoint receives this structure:
 }
 ```
 
-#### Fields description
+## Fields description
 
 | Field                                     | Description                           | Notes                                                        |
 | ----------------------------------------- | ------------------------------------- | ------------------------------------------------------------ |
@@ -37,7 +43,7 @@ The PSMDB Create endpoint receives this structure:
 
 Since the endpoint can set defaults, you can create a PSMDB cluster with a minimum request like this:
 
-```bash
+```shell
 curl -X POST "http://localhost/v1/management/DBaaS/PSMDBCluster/Create" \
     -H "accept: application/json" \
     -H "authorization: Basic YWRtaW46YWRtaW4=" \

diff --git a/docs/api/createpxccluster.md → docs/api/dbaas/create-pxc-cluster.md b/docs/api/createpxccluster.md → docs/api/dbaas/create-pxc-cluster.md
@@ -1,16 +1,22 @@
-### Create PXC Cluster
+---
+title: Create a PXC Cluster
+slug: create-pxc-cluster
+category: 651c00ce1679590036133c8c
+order: 1
+hidden: 0
+---
 
-Once you register the Kubernetes cluster, you can use its name to create database clusters. Here is an example for the PXC cluster. Percona recommends the following the values for the parameters: 
+Once you register a Kubernetes cluster, you can use its name to create database clusters. Here is an example for the PXC cluster. Percona recommends the following the values for the parameters: 
 
-```bash
+```shell
 curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ 
      -H "accept: application/json" \
      -H "authorization: Basic YWRtaW46YWRtaW4=" \
      -H "Content-Type: application/json" \ 
      -d "{ \"kubernetes_cluster_name\": \"my_cluster\", \"name\": \"my-cluster-1\", \"expose\": true, \"params\": { \"cluster_size\": 3, \"pxc\": { \"compute_resources\": { \"cpu_m\": 1000, \"memory_bytes\": 2000000000 }, \"disk_size\": 25000000000, \"image\": \"percona/percona-xtradb-cluster:8.0.25-15.1\" }, \"haproxy\": { \"compute_resources\": { \"cpu_m\": 1000, \"memory_bytes\": 2000000000 } } } }"
 ```
 
-### Request parameters
+## Request parameters
 
 ```
 {
@@ -46,7 +52,7 @@ curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \
 }
 ```
 
-#### Fields description
+### Fields description
 
 |Parameter                              |Description                                     |Notes                                                                |
 |---------------------------------------|------------------------------------------------|---------------------------------------------------------------------|
@@ -69,13 +75,13 @@ curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \
 **Note:** 
 Either ProxySQL or HAProxy should be specified in the request.
 
-#### Minimum request example
+### Minimum request example
 
 Since the API has the defaults mentioned above, the HTTP request can have the Kubernetes cluster name as the only parameter.
 
 Example:
 
-```bash
+```shell
 curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \
     -H "accept: application/json" \
     -H "authorization: Basic YWRtaW46YWRtaW4=" \