Merge branch '11877-public-approval-api-ee-docs' into 'master'

Doc: add project approval rule endpoints

See merge request gitlab-org/gitlab-ce!31455

1 files changed, 238 insertions, 56 deletions

diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md
index cc95689a65f..bf83bfd7e6a 100644
--- a/doc/api/merge_request_approvals.md
+++ b/doc/api/merge_request_approvals.md
@@ -23,36 +23,6 @@ GET /projects/:id/approvals
 
 ```json
 {
-  "approvers": [
-    {
-      "user": {
-        "id": 5,
-        "name": "John Doe6",
-        "username": "user5",
-        "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5"
-      }
-    }
-  ],
-  "approver_groups": [
-    {
-      "group": {
-        "id": 1,
-        "name": "group1",
-        "path": "group1",
-        "description": "",
-        "visibility": "public",
-        "lfs_enabled": false,
-        "avatar_url": null,
-        "web_url": "http://localhost/groups/group1",
-        "request_access_enabled": false,
-        "full_name": "group1",
-        "full_path": "group1",
-        "parent_id": null,
-        "ldap_cn": null,
-        "ldap_access": null
-      }
-    }
-  ],
   "approvals_before_merge": 2,
   "reset_approvals_on_push": true,
   "disable_overriding_approvers_per_merge_request": false
@@ -75,7 +45,7 @@ POST /projects/:id/approvals
 | Attribute                                        | Type    | Required | Description                                                                                         |
 | ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- |
 | `id`                                             | integer | yes      | The ID of a project                                                                                 |
-| `approvals_before_merge`                         | integer | no       | How many approvals are required before an MR can be merged                                          |
+| `approvals_before_merge`                         | integer | no       | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
 | `reset_approvals_on_push`                        | boolean | no       | Reset approvals on a new push                                                                       |
 | `disable_overriding_approvers_per_merge_request` | boolean | no       | Allow/Disallow overriding approvers per MR                                                          |
 | `merge_requests_author_approval`                 | boolean | no       | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve |
@@ -83,20 +53,68 @@ POST /projects/:id/approvals
 
 ```json
 {
-  "approvers": [
-    {
-      "user": {
+  "approvals_before_merge": 2,
+  "reset_approvals_on_push": true,
+  "disable_overriding_approvers_per_merge_request": false,
+  "merge_requests_author_approval": false,
+  "merge_requests_disable_committers_approval": false
+}
+```
+
+### Get project-level rules
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can request information about a project's approval rules using the following endpoint:
+
+```
+GET /projects/:id/approval_rules
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+
+```json
+[
+  {
+    "id": 1,
+    "name": "security",
+    "rule_type": "regular",
+    "eligible_approvers": [
+      {
         "id": 5,
-        "name": "John Doe6",
-        "username": "user5",
-        "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5"
+        "name": "John Doe",
+        "username": "jdoe",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/jdoe"
+      },
+      {
+        "id": 50,
+        "name": "Group Member 1",
+        "username": "group_member_1",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/group_member_1"
       }
-    }
-  ],
-  "approver_groups": [
-    {
-      "group": {
-        "id": 1,
+    ],
+    "approvals_required": 3,
+    "users": [
+      {
+        "id": 5,
+        "name": "John Doe",
+        "username": "jdoe",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/jdoe"
+      }
+    ],
+    "groups": [
+      {
+        "id": 5,
         "name": "group1",
         "path": "group1",
         "description": "",
@@ -111,18 +129,187 @@ POST /projects/:id/approvals
         "ldap_cn": null,
         "ldap_access": null
       }
+    ],
+    "contains_hidden_groups": false
+  }
+]
+```
+
+### Create project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can create project approval rules using the following endpoint:
+
+```
+POST /projects/:id/approval_rules
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `name`               | string  | yes      | The name of the approval rule                             |
+| `approvals_required` | integer | yes      | The number of required approvals for this rule            |
+| `users`              | integer | no       | The ids of users as approvers                             |
+| `groups`             | integer | no       | The ids of groups as approvers                            |
+
+```json
+{
+  "id": 1,
+  "name": "security",
+  "rule_type": "regular",
+  "eligible_approvers": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    },
+    {
+      "id": 50,
+      "name": "Group Member 1",
+      "username": "group_member_1",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/group_member_1"
     }
   ],
-  "approvals_before_merge": 2,
-  "reset_approvals_on_push": true,
-  "disable_overriding_approvers_per_merge_request": false,
-  "merge_requests_author_approval": false,
-  "merge_requests_disable_committers_approval": false
+  "approvals_required": 1,
+  "users": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    }
+  ],
+  "groups": [
+    {
+      "id": 5,
+      "name": "group1",
+      "path": "group1",
+      "description": "",
+      "visibility": "public",
+      "lfs_enabled": false,
+      "avatar_url": null,
+      "web_url": "http://localhost/groups/group1",
+      "request_access_enabled": false,
+      "full_name": "group1",
+      "full_path": "group1",
+      "parent_id": null,
+      "ldap_cn": null,
+      "ldap_access": null
+    }
+  ],
+  "contains_hidden_groups": false
+}
+```
+
+### Update project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can update project approval rules using the following endpoint:
+
+```
+PUT /projects/:id/approval_rules/:approval_rule_id
+```
+
+**Important:** Approvers and groups not in the `users`/`groups` param will be **removed**
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `approval_rule_id`   | integer | yes      | The ID of a approval rule                                 |
+| `name`               | string  | yes      | The name of the approval rule                             |
+| `approvals_required` | integer | yes      | The number of required approvals for this rule            |
+| `users`              | integer | no       | The ids of users as approvers                             |
+| `groups`             | integer | no       | The ids of groups as approvers                            |
+
+```json
+{
+  "id": 1,
+  "name": "security",
+  "rule_type": "regular",
+  "eligible_approvers": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    },
+    {
+      "id": 50,
+      "name": "Group Member 1",
+      "username": "group_member_1",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/group_member_1"
+    }
+  ],
+  "approvals_required": 1,
+  "users": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    }
+  ],
+  "groups": [
+    {
+      "id": 5,
+      "name": "group1",
+      "path": "group1",
+      "description": "",
+      "visibility": "public",
+      "lfs_enabled": false,
+      "avatar_url": null,
+      "web_url": "http://localhost/groups/group1",
+      "request_access_enabled": false,
+      "full_name": "group1",
+      "full_path": "group1",
+      "parent_id": null,
+      "ldap_cn": null,
+      "ldap_access": null
+    }
+  ],
+  "contains_hidden_groups": false
 }
 ```
 
+### Delete project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can delete project approval rules using the following endpoint:
+
+```
+DELETE /projects/:id/approval_rules/:approval_rule_id
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `approval_rule_id`   | integer | yes      | The ID of a approval rule
+
 ### Change allowed approvers
 
+>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
 >**Note:** This API endpoint is only available on 10.6 Starter and above.
 
 If you are allowed to, you can change approvers and approver groups using
@@ -227,8 +414,6 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals
       }
     }
   ],
-  "approvers": [],
-  "approver_groups": []
 }
 ```
 
@@ -249,7 +434,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
 |----------------------|---------|----------|--------------------------------------------|
 | `id`                 | integer | yes      | The ID of a project                        |
 | `merge_request_iid`  | integer | yes      | The IID of MR                              |
-| `approvals_required` | integer | yes      | Approvals required before MR can be merged |
+| `approvals_required` | integer | yes      | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
 
 ```json
 {
@@ -264,14 +449,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
   "merge_status": "cannot_be_merged",
   "approvals_required": 2,
   "approvals_left": 2,
-  "approved_by": [],
-  "approvers": [],
-  "approver_groups": []
+  "approved_by": []
 }
 ```
 
 ### Change allowed approvers for Merge Request
 
+>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
 >**Note:** This API endpoint is only available on 10.6 Starter and above.
 
 If you are allowed to, you can change approvers and approver groups using
@@ -401,8 +585,6 @@ does not match, the response code will be `409`.
       }
     }
   ],
-  "approvers": [],
-  "approver_groups": []
 }
 ```