Merge branch 'docs/cleanup-projects-api' into 'master'

Clean up projects API docs

See merge request !14071

1 files changed, 40 insertions, 187 deletions

diff --git a/doc/api/projects.md b/doc/api/projects.md
index 2d973547d14..3144220e588 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,6 +1,6 @@
 # Projects API
 
-### Project visibility level
+## Project visibility level
 
 Project in GitLab can be either private, internal or public.
 This is determined by the `visibility` field in the project.
@@ -16,16 +16,15 @@ Values for the project visibility level are:
 * `public`:
   The project can be cloned without any authentication.
 
-## List projects
+## List all projects
 
-Get a list of visible projects for authenticated user. When accessed without authentication, only public projects are returned.
+Get a list of all visible projects across GitLab for the authenticated user.
+When accessed without authentication, only public projects are returned.
 
 ```
 GET /projects
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `archived` | boolean | no | Limit by archived status |
@@ -193,16 +192,15 @@ Parameters:
 ]
 ```
 
-### List a user's projects
+## List user projects
 
-Get a list of visible projects for the given user. When accessed without authentication, only public projects are returned.
+Get a list of visible projects for the given user. When accessed without
+authentication, only public projects are returned.
 
 ```
 GET /users/:user_id/projects
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `user_id` | string | yes | The ID or username of the user |
@@ -371,7 +369,7 @@ Parameters:
 ]
 ```
 
-### Get single project
+## Get single project
 
 Get a specific project. This endpoint can be accessed without authentication if
 the project is publicly accessible.
@@ -380,8 +378,6 @@ the project is publicly accessible.
 GET /projects/:id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -485,17 +481,14 @@ Parameters:
 
 Get the users list of a project.
 
-
-Parameters:
+```
+GET /projects/:id/users
+```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `search` | string | no | Search for specific users |
 
-```
-GET /projects/:id/users
-```
-
 ```json
 [
   {
@@ -517,11 +510,11 @@ GET /projects/:id/users
 ]
 ```
 
-### Get project events
+## Get project events
 
-Please refer to the [Events API documentation](events.md#list-a-projects-visible-events)
+Please refer to the [Events API documentation](events.md#list-a-projects-visible-events).
 
-### Create project
+## Create project
 
 Creates a new project owned by the authenticated user.
 
@@ -529,8 +522,6 @@ Creates a new project owned by the authenticated user.
 POST /projects
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
@@ -557,7 +548,7 @@ Parameters:
 | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
 | `ci_config_path` | string | no | The path to CI config file |
 
-### Create project for user
+## Create project for user
 
 Creates a new project owned by the specified user. Available only for admins.
 
@@ -565,8 +556,6 @@ Creates a new project owned by the specified user. Available only for admins.
 POST /projects/user/:user_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `user_id` | integer | yes | The user ID of the project owner |
@@ -595,7 +584,7 @@ Parameters:
 | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
 | `ci_config_path` | string | no | The path to CI config file |
 
-### Edit project
+## Edit project
 
 Updates an existing project.
 
@@ -603,8 +592,6 @@ Updates an existing project.
 PUT /projects/:id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -631,24 +618,24 @@ Parameters:
 | `avatar`    | mixed   | no      | Image file for avatar of the project                |
 | `ci_config_path` | string | no | The path to CI config file |
 
-### Fork project
+## Fork project
 
 Forks a project into the user namespace of the authenticated user or the one provided.
 
-The forking operation for a project is asynchronous and is completed in a background job. The request will return immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project.
+The forking operation for a project is asynchronous and is completed in a
+background job. The request will return immediately. To determine whether the
+fork of the project has completed, query the `import_status` for the new project.
 
 ```
 POST /projects/:id/fork
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to |
 
-### Star a project
+## Star a project
 
 Stars a given project. Returns status code `304` if the project is already starred.
 
@@ -656,8 +643,6 @@ Stars a given project. Returns status code `304` if the project is already starr
 POST /projects/:id/star
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -726,7 +711,7 @@ Example response:
 }
 ```
 
-### Unstar a project
+## Unstar a project
 
 Unstars a given project. Returns status code `304` if the project is not starred.
 
@@ -802,7 +787,7 @@ Example response:
 }
 ```
 
-### Archive a project
+## Archive a project
 
 Archives the project if the user is either admin or the project owner of this project. This action is
 idempotent, thus archiving an already archived project will not change the project.
@@ -896,7 +881,7 @@ Example response:
 }
 ```
 
-### Unarchive a project
+## Unarchive a project
 
 Unarchives the project if the user is either admin or the project owner of this project. This action is
 idempotent, thus unarchiving an non-archived project will not change the project.
@@ -990,7 +975,7 @@ Example response:
 }
 ```
 
-### Remove project
+## Remove project
 
 Removes a project including all associated resources (issues, merge requests etc.)
 
@@ -998,15 +983,11 @@ Removes a project including all associated resources (issues, merge requests etc
 DELETE /projects/:id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 
-## Uploads
-
-### Upload a file
+## Upload a file
 
 Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
 
@@ -1014,8 +995,6 @@ Uploads a file to the specified project to be used in an issue or merge request
 POST /projects/:id/uploads
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1040,15 +1019,11 @@ Returned object:
 }
 ```
 
-**Note**: The returned `url` is relative to the project path.
+>**Note**: The returned `url` is relative to the project path.
 In Markdown contexts, the link is automatically expanded when the format in
 `markdown` is used.
 
-## Project members
-
-Please consult the [Project Members](members.md) documentation.
-
-### Share project with group
+## Share project with group
 
 Allow to share project with group.
 
@@ -1056,8 +1031,6 @@ Allow to share project with group.
 POST /projects/:id/share
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1065,7 +1038,7 @@ Parameters:
 | `group_access` | integer | yes | The permissions level to grant the group |
 | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 |
 
-### Delete a shared project link within a group
+## Delete a shared project link within a group
 
 Unshare the project from the group. Returns `204` and no content on success.
 
@@ -1073,8 +1046,6 @@ Unshare the project from the group. Returns `204` and no content on success.
 DELETE /projects/:id/share/:group_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1097,8 +1068,6 @@ Get a list of project hooks.
 GET /projects/:id/hooks
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1111,8 +1080,6 @@ Get a specific hook for a project.
 GET /projects/:id/hooks/:hook_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1144,8 +1111,6 @@ Adds a hook to a specified project.
 POST /projects/:id/hooks
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1169,8 +1134,6 @@ Edits a hook for a specified project.
 PUT /projects/:id/hooks/:hook_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1196,8 +1159,6 @@ Either the hook is available or not.
 DELETE /projects/:id/hooks/:hook_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1206,126 +1167,16 @@ Parameters:
 Note the JSON response differs if the hook is available or not. If the project hook
 is available before it is returned in the JSON response or an empty response is returned.
 
-## Branches
-
-For more information please consult the [Branches](branches.md) documentation.
-
-### List branches
-
-Lists all branches of a project.
-
-```
-GET /projects/:id/repository/branches
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-
-```json
-[
-  {
-    "name": "async",
-    "commit": {
-      "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca",
-      "parent_ids": [
-        "3f94fc7c85061973edc9906ae170cc269b07ca55"
-      ],
-      "message": "give Caolan credit where it's due (up top)",
-      "author_name": "Jeremy Ashkenas",
-      "author_email": "jashkenas@example.com",
-      "authored_date": "2010-12-08T21:28:50+00:00",
-      "committer_name": "Jeremy Ashkenas",
-      "committer_email": "jashkenas@example.com",
-      "committed_date": "2010-12-08T21:28:50+00:00"
-    },
-    "protected": false,
-    "developers_can_push": false,
-    "developers_can_merge": false
-  },
-  {
-    "name": "gh-pages",
-    "commit": {
-      "id": "101c10a60019fe870d21868835f65c25d64968fc",
-      "parent_ids": [
-          "9c15d2e26945a665131af5d7b6d30a06ba338aaa"
-      ],
-      "message": "Underscore.js 1.5.2",
-      "author_name": "Jeremy Ashkenas",
-      "author_email": "jashkenas@example.com",
-      "authored_date": "2013-09-07T12:58:21+00:00",
-      "committer_name": "Jeremy Ashkenas",
-      "committer_email": "jashkenas@example.com",
-      "committed_date": "2013-09-07T12:58:21+00:00"
-    },
-    "protected": false,
-    "developers_can_push": false,
-    "developers_can_merge": false
-  }
-]
-```
-
-### Single branch
-
-A specific branch of a project.
-
-```
-GET /projects/:id/repository/branches/:branch
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
-| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
-
-### Protect single branch
-
-Protects a single branch of a project.
-
-```
-PUT /projects/:id/repository/branches/:branch/protect
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-
-### Unprotect single branch
-
-Unprotects a single branch of a project.
-
-```
-PUT /projects/:id/repository/branches/:branch/unprotect
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-
 ## Admin fork relation
 
 Allows modification of the forked relationship between existing projects. Available only for admins.
 
-### Create a forked from/to relation between existing projects.
+### Create a forked from/to relation between existing projects
 
 ```
 POST /projects/:id/fork/:forked_from_id
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1337,8 +1188,6 @@ Parameters:
 DELETE /projects/:id/fork
 ```
 
-Parameter:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1353,8 +1202,6 @@ accessible.
 GET /projects
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `search` | string | yes | A string contained in the project name |
@@ -1367,14 +1214,20 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a
 
 ## Start the Housekeeping task for a Project
 
->**Note:** This feature was introduced in GitLab 9.0
+> Introduced in GitLab 9.0.
 
 ```
 POST /projects/:id/housekeeping
 ```
 
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+
+## Branches
+
+Read more in the [Branches](branches.md) documentation.
+
+## Project members
+
+Read more in the [Project members](members.md) documentation.