Skip to content

G
gitlab-ce
Commit b97f9629 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

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

Clean up projects API docs

See merge request !14071
parents ba302454 2247f11a
Show whitespace changes
Inline Side-by-side
Showing with 40 additions and 187 deletions
doc/api/projects.md
View file @ b97f9629
# Projects API # Projects API
### Project visibility level ## Project visibility level
Project in GitLab can be either private, internal or public. Project in GitLab can be either private, internal or public.
This is determined by the `visibility` field in the project. This is determined by the `visibility` field in the project.
...@@ -16,16 +16,15 @@ Values for the project visibility level are: ...@@ -16,16 +16,15 @@ Values for the project visibility level are:
* `public`: * `public`:
The project can be cloned without any authentication. 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 GET /projects
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `archived` | boolean | no | Limit by archived status | | `archived` | boolean | no | Limit by archived status |
...@@ -193,16 +192,15 @@ Parameters: ...@@ -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 GET /users/:user_id/projects
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `user_id` | string | yes | The ID or username of the user | | `user_id` | string | yes | The ID or username of the user |
...@@ -371,7 +369,7 @@ Parameters: ...@@ -371,7 +369,7 @@ Parameters:
] ]
``` ```
### Get single project ## Get single project
Get a specific project. This endpoint can be accessed without authentication if Get a specific project. This endpoint can be accessed without authentication if
the project is publicly accessible. the project is publicly accessible.
...@@ -380,8 +378,6 @@ the project is publicly accessible. ...@@ -380,8 +378,6 @@ the project is publicly accessible.
GET /projects/:id GET /projects/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -485,17 +481,14 @@ Parameters: ...@@ -485,17 +481,14 @@ Parameters:
Get the users list of a project. Get the users list of a project.
```
Parameters: GET /projects/:id/users
```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `search` | string | no | Search for specific users | | `search` | string | no | Search for specific users |
```
GET /projects/:id/users
```
```json ```json
[ [
{ {
...@@ -517,11 +510,11 @@ GET /projects/:id/users ...@@ -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. Creates a new project owned by the authenticated user.
...@@ -529,8 +522,6 @@ Creates a new project owned by the authenticated user. ...@@ -529,8 +522,6 @@ Creates a new project owned by the authenticated user.
POST /projects POST /projects
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
...@@ -557,7 +548,7 @@ Parameters: ...@@ -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 | | `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 | | `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. 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. ...@@ -565,8 +556,6 @@ Creates a new project owned by the specified user. Available only for admins.
POST /projects/user/:user_id POST /projects/user/:user_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The user ID of the project owner | | `user_id` | integer | yes | The user ID of the project owner |
...@@ -595,7 +584,7 @@ Parameters: ...@@ -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 | | `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 | | `ci_config_path` | string | no | The path to CI config file |
### Edit project ## Edit project
Updates an existing project. Updates an existing project.
...@@ -603,8 +592,6 @@ Updates an existing project. ...@@ -603,8 +592,6 @@ Updates an existing project.
PUT /projects/:id PUT /projects/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -631,24 +618,24 @@ Parameters: ...@@ -631,24 +618,24 @@ Parameters:
| `avatar` | mixed | no | Image file for avatar of the project | | `avatar` | mixed | no | Image file for avatar of the project |
| `ci_config_path` | string | no | The path to CI config file | | `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. 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 POST /projects/:id/fork
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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 | | `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. 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 ...@@ -656,8 +643,6 @@ Stars a given project. Returns status code `304` if the project is already starr
POST /projects/:id/star POST /projects/:id/star
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -726,7 +711,7 @@ Example response: ...@@ -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. Unstars a given project. Returns status code `304` if the project is not starred.
...@@ -802,7 +787,7 @@ Example response: ...@@ -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 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. idempotent, thus archiving an already archived project will not change the project.
...@@ -896,7 +881,7 @@ Example response: ...@@ -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 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. idempotent, thus unarchiving an non-archived project will not change the project.
...@@ -990,7 +975,7 @@ Example response: ...@@ -990,7 +975,7 @@ Example response:
} }
``` ```
### Remove project ## Remove project
Removes a project including all associated resources (issues, merge requests etc.) 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 ...@@ -998,15 +983,11 @@ Removes a project including all associated resources (issues, merge requests etc
DELETE /projects/:id DELETE /projects/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. 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 ...@@ -1014,8 +995,6 @@ Uploads a file to the specified project to be used in an issue or merge request
POST /projects/:id/uploads POST /projects/:id/uploads
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -1040,15 +1019,11 @@ Returned object: ...@@ -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 In Markdown contexts, the link is automatically expanded when the format in
`markdown` is used. `markdown` is used.
## Project members ## Share project with group
Please consult the [Project Members](members.md) documentation.
### Share project with group
Allow to share project with group. Allow to share project with group.
...@@ -1056,8 +1031,6 @@ Allow to share project with group. ...@@ -1056,8 +1031,6 @@ Allow to share project with group.
POST /projects/:id/share POST /projects/:id/share
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -1065,7 +1038,7 @@ Parameters: ...@@ -1065,7 +1038,7 @@ Parameters:
| `group_access` | integer | yes | The permissions level to grant the group | | `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 | | `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. 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. ...@@ -1073,8 +1046,6 @@ Unshare the project from the group. Returns `204` and no content on success.
DELETE /projects/:id/share/:group_id DELETE /projects/:id/share/:group_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. ...@@ -1097,8 +1068,6 @@ Get a list of project hooks.
GET /projects/:id/hooks GET /projects/:id/hooks
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. ...@@ -1111,8 +1080,6 @@ Get a specific hook for a project.
GET /projects/:id/hooks/:hook_id GET /projects/:id/hooks/:hook_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. ...@@ -1144,8 +1111,6 @@ Adds a hook to a specified project.
POST /projects/:id/hooks POST /projects/:id/hooks
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. ...@@ -1169,8 +1134,6 @@ Edits a hook for a specified project.
PUT /projects/:id/hooks/:hook_id PUT /projects/:id/hooks/:hook_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `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. ...@@ -1196,8 +1159,6 @@ Either the hook is available or not.
DELETE /projects/:id/hooks/:hook_id DELETE /projects/:id/hooks/:hook_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -1206,126 +1167,16 @@ Parameters: ...@@ -1206,126 +1167,16 @@ Parameters:
Note the JSON response differs if the hook is available or not. If the project hook 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. 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 ## Admin fork relation
Allows modification of the forked relationship between existing projects. Available only for admins. 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 POST /projects/:id/fork/:forked_from_id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -1337,8 +1188,6 @@ Parameters: ...@@ -1337,8 +1188,6 @@ Parameters:
DELETE /projects/:id/fork DELETE /projects/:id/fork
``` ```
Parameter:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...@@ -1353,8 +1202,6 @@ accessible. ...@@ -1353,8 +1202,6 @@ accessible.
GET /projects GET /projects
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `search` | string | yes | A string contained in the project name | | `search` | string | yes | A string contained in the project name |
...@@ -1367,14 +1214,20 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a ...@@ -1367,14 +1214,20 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a
## Start the Housekeeping task for a Project ## 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 POST /projects/:id/housekeeping
``` ```
Parameters:
| Attribute | Type | Required | Description | | 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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7