Merge branch 'docs-api-merge-new-2-ee' into 'master'

(EE Port) Docs: Update api docs to align to CE

See merge request gitlab-org/gitlab-ee!14523

doc/api/group_boards.md

@@ -70,6 +70,59 @@ Example response:
 ]
 ```
 
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group boards. Refer to the table
+above to see what enpoint(s) belong to each tier.
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+]
+```
+
 ## Single board
 
 Gets a single board.
@@ -134,9 +187,59 @@ Example response:
   }
 ```
 
-## Create a board
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group boards:
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+```
+
+## Create a Group Issue Board **[PREMIUM]**
 
-Creates a board.
+Creates a Group Issue Board.
 
 ```
 POST /groups/:id/boards
@@ -198,11 +301,11 @@ Example response:
   }
 ```
 
-## Update a board
+## Update a Group Issue Board **[PREMIUM]**
 
 > [Introduced][ee-5954] in GitLab 11.1.
 
-Updates a board.
+Updates a Group Issue Board.
 
 ```
 PUT /groups/:id/boards/:board_id
@@ -267,9 +370,9 @@ Example response:
   }
 ```
 
-## Delete a board
+## Delete a Group Issue Board **[PREMIUM]**
 
-Deletes a board.
+Deletes a Group Issue Board.
 
 ```
 DELETE /groups/:id/boards/:board_id

doc/api/groups.md

@@ -377,6 +377,16 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters:
+
+Additional response parameters: **[STARTER]**
+
+```json
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+```
+
 When adding the parameter `with_projects=false`, projects will not be returned.
 
 ```bash
@@ -414,15 +424,15 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `name` | string | yes | The name of the group |
-| `path` | string | yes | The path of the group |
-| `description` | string | no | The group's description |
-| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. |
-| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
-| `request_access_enabled` | boolean | no | Allow users to request member access. |
-| `parent_id` | integer | no | The parent group id for creating nested group. |
-| `shared_runners_minutes_limit` | integer | no | (admin-only) Pipeline minutes quota for this group. |
-| `extra_shared_runners_minutes_limit` | integer | no | (admin-only) Extra pipeline minutes quota for this group. |
+| `name`                               | string  | yes | The name of the group |
+| `path`                               | string  | yes | The path of the group |
+| `description`                        | string  | no  | The group's description |
+| `visibility`                         | string  | no  | The group's visibility. Can be `private`, `internal`, or `public`. |
+| `lfs_enabled`                        | boolean | no  | Enable/disable Large File Storage (LFS) for the projects in this group |
+| `request_access_enabled`             | boolean | no  | Allow users to request member access. |
+| `parent_id`                          | integer | no  | The parent group ID for creating nested group. |
+| `shared_runners_minutes_limit`       | integer | no  | **[STARTER ONLY]** Pipeline minutes quota for this group. |
+| `extra_shared_runners_minutes_limit` | integer | no  | **[STARTER ONLY]** Extra pipeline minutes quota for this group. |
 
 ## Transfer project to group
 
@@ -449,18 +459,18 @@ PUT /groups/:id
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the group |
-| `name` | string | no | The name of the group |
-| `path` | string | no | The path of the group |
-| `description` | string | no | The description of the group |
-| `membership_lock` | boolean | no | Prevent adding new members to project membership within this group |
-| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group |
-| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
-| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
-| `request_access_enabled` | boolean | no | Allow users to request member access. |
-| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from |
-| `shared_runners_minutes_limit` | integer | no | (admin-only) Pipeline minutes quota for this group |
-| `extra_shared_runners_minutes_limit` | integer | no | (admin-only) Extra pipeline minutes quota for this group |
+| `id`                                 | integer | yes | The ID of the group |
+| `name`                               | string  | no  | The name of the group |
+| `path`                               | string  | no  | The path of the group |
+| `description`                        | string  | no  | The description of the group |
+| `membership_lock`                    | boolean | no  | **[STARTER]** Prevent adding new members to project membership within this group |
+| `share_with_group_lock`              | boolean | no  | Prevent sharing a project with another group within this group |
+| `visibility`                         | string  | no  | The visibility level of the group. Can be `private`, `internal`, or `public`. |
+| `lfs_enabled` (optional)             | boolean | no  | Enable/disable Large File Storage (LFS) for the projects in this group |
+| `request_access_enabled`             | boolean | no  | Allow users to request member access. |
+| `file_template_project_id`           | integer | no  | **[PREMIUM]** The ID of a project to load custom file templates from |
+| `shared_runners_minutes_limit`       | integer | no  | **[STARTER ONLY]** Pipeline minutes quota for this group |
+| `extra_shared_runners_minutes_limit` | integer | no  | **[STARTER ONLY]** Extra pipeline minutes quota for this group |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
@@ -560,7 +570,7 @@ GET /groups?search=foobar
 ]
 ```
 
-## Sync group with LDAP
+## Sync group with LDAP **[CORE ONLY]**
 
 Syncs the group with its linked LDAP group. Only available to group owners and administrators.
 
@@ -576,9 +586,9 @@ Parameters:
 
 Please consult the [Group Members](members.md) documentation.
 
-### Add LDAP group link
+### Add LDAP group link **[CORE ONLY]**
 
-Adds LDAP group link
+Adds an LDAP group link.
 
 ```
 POST /groups/:id/ldap_group_links
@@ -591,9 +601,9 @@ Parameters:
 - `group_access` (required) - Minimum access level for members of the LDAP group
 - `provider` (required) - LDAP provider for the LDAP group
 
-### Delete LDAP group link
+### Delete LDAP group link **[CORE ONLY]**
 
-Deletes a LDAP group link
+Deletes an LDAP group link.
 
 ```
 DELETE /groups/:id/ldap_group_links/:cn

doc/api/namespaces.md

@@ -55,7 +55,21 @@ Example response:
 ]
 ```
 
-**Note**: `members_count_with_descendants` and `plan` are presented only for group maintainers/owners.
+Users on GitLab.com [Bronze or higher](https://about.gitlab.com/pricing/#gitlab-com) may also see
+the `plan` parameter associated with a namespace:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "user1",
+    "plan": "bronze",
+    ...
+  }
+]
+```
+
+**Note**: Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **[BRONZE ONLY]**.
 
 ## Search for namespace
 

doc/api/notification_settings.md

 # Notification settings API
 
->**Note:** This feature was [introduced][ce-5632] in GitLab 8.12.
+>**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.
 
 **Valid notification levels**
 
@@ -17,23 +17,22 @@ custom
 
 If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized:
 
-```
-new_note
-new_issue
-reopen_issue
-close_issue
-reassign_issue
-issue_due
-new_merge_request
-push_to_merge_request
-reopen_merge_request
-close_merge_request
-reassign_merge_request
-merge_merge_request
-failed_pipeline
-success_pipeline
-new_epic
-```
+- `new_note`
+- `new_issue`
+- `reopen_issue`
+- `close_issue`
+- `reassign_issue`
+- `issue_due`
+- `new_merge_request`
+- `push_to_merge_request`
+- `reopen_merge_request`
+- `close_merge_request`
+- `reassign_merge_request`
+- `merge_merge_request`
+- `failed_pipeline`
+- `success_pipeline`
+- `new_epic` **[ULTIMATE]**
+
 
 ## Global notification settings
 
@@ -86,7 +85,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
-| `new_epic` | boolean | no | Enable/disable this notification ([Introduced][ee-6626] in 11.3) |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
 Example response:
 
@@ -155,7 +154,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
-| `new_epic` | boolean | no | Enable/disable this notification ([Introduced][ee-6626] in 11.3) |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
 Example responses:
 
@@ -186,5 +185,17 @@ Example responses:
 }
 ```
 
-[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632
-[ee-6626]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626
+Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) will also see
+the `new_epic` parameter:
+
+```json
+{
+  "level": "custom",
+  "events": {
+    "new_note": true,
+    "new_issue": false,
+    "new_epic": false,
+    ...
+  }
+}
+```

doc/api/protected_branches.md

@@ -56,6 +56,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.
@@ -97,6 +127,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
@@ -112,15 +169,46 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitla
 
 | 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) |
-| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
-| `allowed_to_push` | array | no | Array of access levels allowed to push, with each described by a hash |
-| `allowed_to_merge` | array | no | Array of access levels allowed to merge, with each described by a hash |
-| `allowed_to_unprotect` | array | no | Array of access levels allowed to unprotect, with each described by a hash |
+| `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,
+      "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,
+      "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:
 
@@ -153,7 +241,7 @@ Example response:
 }
 ```
 
-### Example with user / group level access
+### 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.

doc/api/users.md

@@ -224,6 +224,8 @@ Parameters:
 
 - `id` (required) - The ID of a user
 
+Example Responses:
+
 ```json
 {
   "id": 1,
@@ -266,6 +268,19 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: **[STARTER]**
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133
+  ...
+}
+```
+
 You can include the user's [custom attributes](custom_attributes.md) in the response with:
 
 ```
@@ -289,32 +304,30 @@ POST /users
 
 Parameters:
 
-- `email` (required)                 - Email
-- `password` (optional)              - Password
-- `reset_password` (optional)        - Send user password reset link - true or false (default)
-- `force_random_password` (optional) - Set user password to a random value - true or false (default)
-- `username` (required)              - Username
-- `name` (required)                  - Name
-- `skype` (optional)                 - Skype ID
-- `linkedin` (optional)              - LinkedIn
-- `twitter` (optional)               - Twitter account
-- `website_url` (optional)           - Website URL
-- `organization` (optional)          - Organization name
-- `projects_limit` (optional)        - Number of projects user can create
-- `extern_uid` (optional)            - External UID
-- `provider` (optional)              - External provider name
-- `group_id_for_saml` (optional)     - ID of group where SAML has been configured
-- `bio` (optional)                   - User's biography
-- `location` (optional)              - User's location
-- `public_email` (optional)          - The public email of the user
-- `admin` (optional)                 - User is admin - true or false (default)
-- `can_create_group` (optional)      - User can create groups - true or false
-- `skip_confirmation` (optional)     - Skip confirmation - true or false (default)
-- `external` (optional)              - Flags the user as external - true or false(default)
-- `avatar` (optional)                - Image file for user's avatar
-- `private_profile` (optional)       - User's profile is private - true or false
-- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
-- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
+- `email` (required)             - Email
+- `password` (optional)          - Password
+- `reset_password` (optional)    - Send user password reset link - true or false(default)
+- `username` (required)          - Username
+- `name` (required)              - Name
+- `skype` (optional)             - Skype ID
+- `linkedin` (optional)          - LinkedIn
+- `twitter` (optional)           - Twitter account
+- `website_url` (optional)       - Website URL
+- `organization` (optional)      - Organization name
+- `projects_limit` (optional)    - Number of projects user can create
+- `extern_uid` (optional)        - External UID
+- `provider` (optional)          - External provider name
+- `bio` (optional)               - User's biography
+- `location` (optional)          - User's location
+- `public_email` (optional)      - The public email of the user
+- `admin` (optional)             - User is admin - true or false (default)
+- `can_create_group` (optional)  - User can create groups - true or false
+- `skip_confirmation` (optional) - Skip confirmation - true or false (default)
+- `external` (optional)          - Flags the user as external - true or false(default)
+- `avatar` (optional)            - Image file for user's avatar
+- `private_profile` (optional)   - User's profile is private - true or false
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **[STARTER]**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
 ## User modification
 
@@ -350,6 +363,8 @@ Parameters:
 - `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
 - `avatar` (optional)              - Image file for user's avatar
 - `private_profile` (optional)     - User's profile is private - true or false
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **[STARTER]**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
 On password update, user will be forced to change it upon next login.
 Note, at the moment this method does only return a `404` error,