Clean up projects API docs
This commit is contained in:
parent
a0c13698f9
commit
2247f11afd
|
@ -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 |
|
||||
|
@ -191,16 +190,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 |
|
||||
|
@ -367,7 +365,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.
|
||||
|
@ -376,8 +374,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) |
|
||||
|
@ -480,17 +476,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
|
||||
[
|
||||
{
|
||||
|
@ -512,11 +505,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.
|
||||
|
||||
|
@ -524,8 +517,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. |
|
||||
|
@ -551,7 +542,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.
|
||||
|
||||
|
@ -559,8 +550,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 |
|
||||
|
@ -588,7 +577,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.
|
||||
|
||||
|
@ -596,8 +585,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) |
|
||||
|
@ -623,24 +610,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.
|
||||
|
||||
|
@ -648,8 +635,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) |
|
||||
|
@ -717,7 +702,7 @@ Example response:
|
|||
}
|
||||
```
|
||||
|
||||
### Unstar a project
|
||||
## Unstar a project
|
||||
|
||||
Unstars a given project. Returns status code `304` if the project is not starred.
|
||||
|
||||
|
@ -792,7 +777,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.
|
||||
|
@ -885,7 +870,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.
|
||||
|
@ -978,7 +963,7 @@ Example response:
|
|||
}
|
||||
```
|
||||
|
||||
### Remove project
|
||||
## Remove project
|
||||
|
||||
Removes a project including all associated resources (issues, merge requests etc.)
|
||||
|
||||
|
@ -986,15 +971,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.
|
||||
|
||||
|
@ -1002,8 +983,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) |
|
||||
|
@ -1028,15 +1007,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.
|
||||
|
||||
|
@ -1044,8 +1019,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) |
|
||||
|
@ -1053,7 +1026,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.
|
||||
|
||||
|
@ -1061,8 +1034,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) |
|
||||
|
@ -1085,8 +1056,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) |
|
||||
|
@ -1099,8 +1068,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) |
|
||||
|
@ -1132,8 +1099,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) |
|
||||
|
@ -1157,8 +1122,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) |
|
||||
|
@ -1184,8 +1147,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) |
|
||||
|
@ -1194,126 +1155,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) |
|
||||
|
@ -1325,8 +1176,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) |
|
||||
|
@ -1341,8 +1190,6 @@ accessible.
|
|||
GET /projects
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
| Attribute | Type | Required | Description |
|
||||
| --------- | ---- | -------- | ----------- |
|
||||
| `search` | string | yes | A string contained in the project name |
|
||||
|
@ -1355,14 +1202,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.
|
||||
|
|
Loading…
Reference in New Issue