Merge protected_branches api doc from EE to CEdocs-api-merge-new-1

(cherry picked from commit 4bbc8d076a63cd02e1a5673646cc93ab0e310b59)

1 files changed, 149 insertions, 5 deletions

diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
index a261bb75be5..6e41584afef 100644
--- a/doc/api/protected_branches.md
+++ b/doc/api/protected_branches.md
@@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
 0  => No access
 30 => Developer access
 40 => Maintainer access
+60 => Admin access
 ```
 
 ## List protected branches
@@ -51,6 +52,36 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+[
+  {
+    "name": "master",
+    "push_access_levels": [
+      {
+        "access_level": 40,
+        "user_id": null,
+        "group_id": null,
+        "access_level_description": "Maintainers"
+      }
+    ],
+    "merge_access_levels": [
+      {
+        "access_level": null,
+        "user_id": null,
+        "group_id": 1234,
+        "access_level_description": "Example Merge Group"
+      }
+    ]
+  },
+  ...
+]
+```
+
 ## Get a single protected branch or wildcard protected branch
 
 Gets a single protected branch or wildcard protected branch.
@@ -88,6 +119,33 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+{
+  "name": "master",
+  "push_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": null,
+      "user_id": null,
+      "group_id": 1234,
+      "access_level_description": "Example Merge Group"
+    }
+  ]
+}
+```
+
 ## Protect repository branches
 
 Protects a single repository branch or several project repository
@@ -98,15 +156,47 @@ POST /projects/:id/protected_branches
 ```
 
 ```bash
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40'
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `name` | string | yes | The name of the branch or wildcard |
-| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
-| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `id`                     | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name`                   | string         | yes | The name of the branch or wildcard |
+| `push_access_level`      | string         | no  | Access levels allowed to push (defaults: `40`, maintainer access level) |
+| `merge_access_level`     | string         | no  | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `unprotect_access_level` | string         | no  | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
+| `allowed_to_push`        | array          | no  | **[STARTER]** Array of access levels allowed to push, with each described by a hash |
+| `allowed_to_merge`       | array          | no  | **[STARTER]** Array of access levels allowed to merge, with each described by a hash |
+| `allowed_to_unprotect`   | array          | no  | **[STARTER]**Array of access levels allowed to unprotect, with each described by a hash |
+
+Example response:
+
+```json
+{
+  "name": "*-stable",
+  "push_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
 
 Example response:
 
@@ -116,13 +206,65 @@ Example response:
   "push_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
     }
   ],
   "merge_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+### Example with user / group level access **[STARTER]**
+
+Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
+form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE.
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1'
+```
+
+Example response:
+
+```json
+{
+  "name":"*-stable",
+  "push_access_levels": [
+    {
+      "access_level":null,
+      "user_id":1,
+      "group_id":null,
+      "access_level_description":"Administrator"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
+    }
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
     }
   ]
 }
@@ -144,3 +286,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the branch |
+
+[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity"