diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/README.md | 108 | ||||
| -rw-r--r-- | doc/api/branches.md | 23 | ||||
| -rw-r--r-- | doc/api/commits.md | 15 | ||||
| -rw-r--r-- | doc/api/deploy_keys.md | 28 | ||||
| -rw-r--r-- | doc/api/issues.md | 47 | ||||
| -rw-r--r-- | doc/api/merge_requests.md | 67 | ||||
| -rw-r--r-- | doc/api/milestones.md | 30 | ||||
| -rw-r--r-- | doc/api/project_snippets.md | 37 | ||||
| -rw-r--r-- | doc/api/repository_files.md | 36 | ||||
| -rw-r--r-- | doc/api/system_hooks.md | 14 | ||||
| -rw-r--r-- | doc/api/users.md | 114 |
11 files changed, 230 insertions, 289 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index acd2f524beb..e91d3af59d7 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -2,31 +2,31 @@ ## Resources -+ [Users](users.md) -+ [Session](session.md) -+ [Projects](projects.md) -+ [Project Snippets](project_snippets.md) -+ [Repositories](repositories.md) -+ [Repository Files](repository_files.md) -+ [Commits](commits.md) -+ [Branches](branches.md) -+ [Merge Requests](merge_requests.md) -+ [Issues](issues.md) -+ [Milestones](milestones.md) -+ [Notes](notes.md) (comments) -+ [Deploy Keys](deploy_keys.md) -+ [System Hooks](system_hooks.md) -+ [Groups](groups.md) +- [Users](users.md) +- [Session](session.md) +- [Projects](projects.md) +- [Project Snippets](project_snippets.md) +- [Repositories](repositories.md) +- [Repository Files](repository_files.md) +- [Commits](commits.md) +- [Branches](branches.md) +- [Merge Requests](merge_requests.md) +- [Issues](issues.md) +- [Milestones](milestones.md) +- [Notes](notes.md) (comments) +- [Deploy Keys](deploy_keys.md) +- [System Hooks](system_hooks.md) +- [Groups](groups.md) ## Clients -+ [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP -+ [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com) -+ [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby -+ [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python -+ [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java -+ [node-gitlab](https://github.com/moul/node-gitlab) - Node.js -+ [NGitLab](https://github.com/Scooletz/NGitLab) - .NET +- [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP +- [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com) +- [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby +- [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python +- [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java +- [node-gitlab](https://github.com/moul/node-gitlab) - Node.js +- [NGitLab](https://github.com/Scooletz/NGitLab) - .NET ## Introduction @@ -54,41 +54,35 @@ Example for a valid API request using curl and authentication via header: curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects" ``` - The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. - - ## Status codes -The API is designed to return different status codes according to context and action. In this way -if a request results in an error the caller is able to get insight into what went wrong, e.g. -status code `400 Bad Request` is returned if a required attribute is missing from the request. -The following list gives an overview of how the API functions generally behave. +The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave. API request types: -* `GET` requests access one or more resources and return the result as JSON -* `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON -* `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON -* `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not. - +- `GET` requests access one or more resources and return the result as JSON +- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON +- `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON +- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not. The following list shows the possible return codes for API requests. Return values: -* `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON -* `201 Created` - The `POST` request was successful and the resource is returned as JSON -* `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given -* `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above -* `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project -* `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found -* `405 Method Not Allowed` - The request is not supported -* `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists -* `500 Server Error` - While handling the request something went wrong on the server side +- `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON +- `201 Created` - The `POST` request was successful and the resource is returned as JSON +- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given +- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above +- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project +- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found +- `405 Method Not Allowed` - The request is not supported +- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists +- `500 Server Error` - While handling the request something went wrong on the server side ## Sudo + All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass `sudo` parameter by url or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals). If a non administrative `private_token` is provided then an error message will be returned with status code 403: @@ -112,16 +106,17 @@ Example of a valid API with sudo request: ``` GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username ``` + ``` GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23 ``` - Example for a valid API request with sudo using curl and authentication via header: ``` curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "http://example.com/api/v3/projects" ``` + ``` curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects" ``` @@ -130,24 +125,21 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http:// When listing resources you can pass the following parameters: -+ `page` (default: `1`) - page number -+ `per_page` (default: `20`, max: `100`) - number of items to list per page +- `page` (default: `1`) - page number +- `per_page` (default: `20`, max: `100`) - number of items to list per page -[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. -These have `rel` prev/next/first/last and contain the relevant url. -Please use these instead of generating your own urls. +[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own urls. ## id vs iid -When you work with API you may notice two similar fields in api entites: id and iid. -The main difference between them is scope. Example: +When you work with API you may notice two similar fields in api entites: id and iid. The main difference between them is scope. Example: + +Issue: -Issue - id: 46 - iid: 5 + id: 46 + iid: 5 -* id - is uniq across all Issues table. It used for any api calls. -* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. +- id - is uniq across all Issues table. It used for any api calls. +- iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. -So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json` -But when you want to create a link to web page - use `http:://host/project/issues/:iid.json` +So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use `http:://host/project/issues/:iid.json` diff --git a/doc/api/branches.md b/doc/api/branches.md index bb2d3fec09d..f695b48fe2f 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -10,7 +10,7 @@ GET /projects/:id/repository/branches Parameters: -+ `id` (required) - The ID of a project +- `id` (required) - The ID of a project ```json [ @@ -52,8 +52,8 @@ GET /projects/:id/repository/branches/:branch Parameters: -+ `id` (required) - The ID of a project -+ `branch` (required) - The name of the branch +- `id` (required) - The ID of a project +- `branch` (required) - The name of the branch ```json { @@ -82,7 +82,6 @@ Parameters: } ``` - ## Protect repository branch Protects a single project repository branch. This is an idempotent function, protecting an already @@ -94,8 +93,8 @@ PUT /projects/:id/repository/branches/:branch/protect Parameters: -+ `id` (required) - The ID of a project -+ `branch` (required) - The name of the branch +- `id` (required) - The ID of a project +- `branch` (required) - The name of the branch ```json { @@ -124,7 +123,6 @@ Parameters: } ``` - ## Unprotect repository branch Unprotects a single project repository branch. This is an idempotent function, unprotecting an already @@ -136,8 +134,8 @@ PUT /projects/:id/repository/branches/:branch/unprotect Parameters: -+ `id` (required) - The ID of a project -+ `branch` (required) - The name of the branch +- `id` (required) - The ID of a project +- `branch` (required) - The name of the branch ```json { @@ -168,16 +166,15 @@ Parameters: ## Create repository branch - ``` POST /projects/:id/repository/branches ``` Parameters: -+ `id` (required) - The ID of a project -+ `branch_name` (required) - The name of the branch -+ `ref` (required) - Create branch from commit sha or existing branch +- `id` (required) - The ID of a project +- `branch_name` (required) - The name of the branch +- `ref` (required) - Create branch from commit sha or existing branch ```json { diff --git a/doc/api/commits.md b/doc/api/commits.md index 241fe0e585a..d55b34c0c1f 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,8 +10,8 @@ GET /projects/:id/repository/commits Parameters: -+ `id` (required) - The ID of a project -+ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch +- `id` (required) - The ID of a project +- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch ```json [ @@ -44,8 +44,8 @@ GET /projects/:id/repository/commits/:sha Parameters: -+ `id` (required) - The ID of a project -+ `sha` (required) - The commit hash or name of a repository branch or tag +- `id` (required) - The ID of a project +- `sha` (required) - The commit hash or name of a repository branch or tag ```json { @@ -63,7 +63,6 @@ Parameters: } ``` - ## Get the diff of a commit Get the diff of a commit in a project. @@ -74,8 +73,8 @@ GET /projects/:id/repository/commits/:sha/diff Parameters: -+ `id` (required) - The ID of a project -+ `sha` (required) - The name of a repository branch or tag or if not given the default branch +- `id` (required) - The ID of a project +- `sha` (required) - The name of a repository branch or tag or if not given the default branch ```json [ @@ -91,5 +90,3 @@ Parameters: } ] ``` - - diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 6aa7be93c01..e4492fc609c 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -1,6 +1,6 @@ # Deploy Keys -### List deploy keys +## List deploy keys Get a list of a project's deploy keys. @@ -10,7 +10,7 @@ GET /projects/:id/keys Parameters: -+ `id` (required) - The ID of the project +- `id` (required) - The ID of the project ```json [ @@ -29,8 +29,7 @@ Parameters: ] ``` - -### Single deploy key +## Single deploy key Get a single key. @@ -40,8 +39,8 @@ GET /projects/:id/keys/:key_id Parameters: -+ `id` (required) - The ID of the project -+ `key_id` (required) - The ID of the deploy key +- `id` (required) - The ID of the project +- `key_id` (required) - The ID of the deploy key ```json { @@ -52,8 +51,7 @@ Parameters: } ``` - -### Add deploy key +## Add deploy key Creates a new deploy key for a project. If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user @@ -64,12 +62,11 @@ POST /projects/:id/keys Parameters: -+ `id` (required) - The ID of the project -+ `title` (required) - New deploy key's title -+ `key` (required) - New deploy key +- `id` (required) - The ID of the project +- `title` (required) - New deploy key's title +- `key` (required) - New deploy key - -### Delete deploy key +## Delete deploy key Delete a deploy key from a project @@ -79,6 +76,5 @@ DELETE /projects/:id/keys/:key_id Parameters: -+ `id` (required) - The ID of the project -+ `key_id` (required) - The ID of the deploy key - +- `id` (required) - The ID of the project +- `key_id` (required) - The ID of the deploy key diff --git a/doc/api/issues.md b/doc/api/issues.md index c769d7bb69a..f775d502a6d 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -73,7 +73,6 @@ GET /issues ] ``` - ## List project issues Get a list of project issues. This function accepts pagination parameters `page` and `per_page` @@ -85,8 +84,7 @@ GET /projects/:id/issues Parameters: -+ `id` (required) - The ID of a project - +- `id` (required) - The ID of a project ## Single issue @@ -98,8 +96,8 @@ GET /projects/:id/issues/:issue_id Parameters: -+ `id` (required) - The ID of a project -+ `issue_id` (required) - The ID of a project issue +- `id` (required) - The ID of a project +- `issue_id` (required) - The ID of a project issue ```json { @@ -142,7 +140,6 @@ Parameters: } ``` - ## New issue Creates a new project issue. @@ -153,13 +150,12 @@ POST /projects/:id/issues Parameters: -+ `id` (required) - The ID of a project -+ `title` (required) - The title of an issue -+ `description` (optional) - The description of an issue -+ `assignee_id` (optional) - The ID of a user to assign issue -+ `milestone_id` (optional) - The ID of a milestone to assign issue -+ `labels` (optional) - Comma-separated label names for an issue - +- `id` (required) - The ID of a project +- `title` (required) - The title of an issue +- `description` (optional) - The description of an issue +- `assignee_id` (optional) - The ID of a user to assign issue +- `milestone_id` (optional) - The ID of a milestone to assign issue +- `labels` (optional) - Comma-separated label names for an issue ## Edit issue @@ -171,21 +167,18 @@ PUT /projects/:id/issues/:issue_id Parameters: -+ `id` (required) - The ID of a project -+ `issue_id` (required) - The ID of a project's issue -+ `title` (optional) - The title of an issue -+ `description` (optional) - The description of an issue -+ `assignee_id` (optional) - The ID of a user to assign issue -+ `milestone_id` (optional) - The ID of a milestone to assign issue -+ `labels` (optional) - Comma-separated label names for an issue -+ `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it) - +- `id` (required) - The ID of a project +- `issue_id` (required) - The ID of a project's issue +- `title` (optional) - The title of an issue +- `description` (optional) - The description of an issue +- `assignee_id` (optional) - The ID of a user to assign issue +- `milestone_id` (optional) - The ID of a milestone to assign issue +- `labels` (optional) - Comma-separated label names for an issue +- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it) ## Delete existing issue (**Deprecated**) -The function is deprecated and returns a `405 Method Not Allowed` -error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with -parameter `closed` set to 1. +The function is deprecated and returns a `405 Method Not Allowed` error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with parameter `closed` set to 1. ``` DELETE /projects/:id/issues/:issue_id @@ -193,8 +186,8 @@ DELETE /projects/:id/issues/:issue_id Parameters: -+ `id` (required) - The project ID -+ `issue_id` (required) - The ID of the issue +- `id` (required) - The project ID +- `issue_id` (required) - The ID of the issue ## Comments on issues diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 284c2befe6f..27c0d644e11 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -2,11 +2,7 @@ ## List merge requests -Get all merge requests for this project. -The `state` parameter can be used to get only merge requests with a -given state (`opened`, `closed`, or `merged`) or all of them (`all`). -The pagination parameters `page` and `per_page` can be used to restrict the -list of merge requests. +Get all merge requests for this project. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. ``` GET /projects/:id/merge_requests @@ -16,8 +12,8 @@ GET /projects/:id/merge_requests?state=all Parameters: -+ `id` (required) - The ID of a project -+ `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed` +- `id` (required) - The ID of a project +- `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed` ```json [ @@ -51,7 +47,6 @@ Parameters: ] ``` - ## Get single MR Shows information about a single merge request. @@ -62,8 +57,8 @@ GET /projects/:id/merge_request/:merge_request_id Parameters: -+ `id` (required) - The ID of a project -+ `merge_request_id` (required) - The ID of MR +- `id` (required) - The ID of a project +- `merge_request_id` (required) - The ID of MR ```json { @@ -95,7 +90,6 @@ Parameters: } ``` - ## Create MR Creates a new merge request. @@ -106,12 +100,12 @@ POST /projects/:id/merge_requests Parameters: -+ `id` (required) - The ID of a project -+ `source_branch` (required) - The source branch -+ `target_branch` (required) - The target branch -+ `assignee_id` (optional) - Assignee user ID -+ `title` (required) - Title of MR -+ `target_project_id` (optional) - The target project (numeric id) +- `id` (required) - The ID of a project +- `source_branch` (required) - The source branch +- `target_branch` (required) - The target branch +- `assignee_id` (optional) - Assignee user ID +- `title` (required) - Title of MR +- `target_project_id` (optional) - The target project (numeric id) ```json { @@ -142,7 +136,6 @@ Parameters: } ``` - ## Update MR Updates an existing merge request. You can change branches, title, or even close the MR. @@ -153,13 +146,13 @@ PUT /projects/:id/merge_request/:merge_request_id Parameters: -+ `id` (required) - The ID of a project -+ `merge_request_id` (required) - ID of MR -+ `source_branch` - The source branch -+ `target_branch` - The target branch -+ `assignee_id` - Assignee user ID -+ `title` - Title of MR -+ `state_event` - New state (close|reopen|merge) +- `id` (required) - The ID of a project +- `merge_request_id` (required) - ID of MR +- `source_branch` - The source branch +- `target_branch` - The target branch +- `assignee_id` - Assignee user ID +- `title` - Title of MR +- `state_event` - New state (close|reopen|merge) ```json { @@ -190,13 +183,16 @@ Parameters: } ``` - ## Accept MR Merge changes submitted with MR usign this API. + If merge success you get 200 OK. + If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged' + If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' + If you dont have permissions to accept this merge request - you get 401 ``` @@ -205,9 +201,9 @@ PUT /projects/:id/merge_request/:merge_request_id/merge Parameters: -+ `id` (required) - The ID of a project -+ `merge_request_id` (required) - ID of MR -+ `merge_commit_message` (optional) - Custom merge commit message +- `id` (required) - The ID of a project +- `merge_request_id` (required) - ID of MR +- `merge_commit_message` (optional) - Custom merge commit message ```json { @@ -238,7 +234,6 @@ Parameters: } ``` - ## Post comment to MR Adds a comment to a merge request. @@ -249,10 +244,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments Parameters: -+ `id` (required) - The ID of a project -+ `merge_request_id` (required) - ID of merge request -+ `note` (required) - Text of comment - +- `id` (required) - The ID of a project +- `merge_request_id` (required) - ID of merge request +- `note` (required) - Text of comment ```json { @@ -268,7 +262,6 @@ Parameters: } ``` - ## Get the comments on a MR Gets all the comments associated with a merge request. @@ -279,8 +272,8 @@ GET /projects/:id/merge_request/:merge_request_id/comments Parameters: -+ `id` (required) - The ID of a project -+ `merge_request_id` (required) - ID of merge request +- `id` (required) - The ID of a project +- `merge_request_id` (required) - ID of merge request ```json [ diff --git a/doc/api/milestones.md b/doc/api/milestones.md index b0f355b9a0c..2f525327504 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -26,8 +26,7 @@ GET /projects/:id/milestones Parameters: -+ `id` (required) - The ID of a project - +- `id` (required) - The ID of a project ## Get single milestone @@ -39,9 +38,8 @@ GET /projects/:id/milestones/:milestone_id Parameters: -+ `id` (required) - The ID of a project -+ `milestone_id` (required) - The ID of a project milestone - +- `id` (required) - The ID of a project +- `milestone_id` (required) - The ID of a project milestone ## Create new milestone @@ -53,11 +51,10 @@ POST /projects/:id/milestones Parameters: -+ `id` (required) - The ID of a project -+ `title` (required) - The title of an milestone -+ `description` (optional) - The description of the milestone -+ `due_date` (optional) - The due date of the milestone - +- `id` (required) - The ID of a project +- `title` (required) - The title of an milestone +- `description` (optional) - The description of the milestone +- `due_date` (optional) - The due date of the milestone ## Edit milestone @@ -69,10 +66,9 @@ PUT /projects/:id/milestones/:milestone_id Parameters: -+ `id` (required) - The ID of a project -+ `milestone_id` (required) - The ID of a project milestone -+ `title` (optional) - The title of a milestone -+ `description` (optional) - The description of a milestone -+ `due_date` (optional) - The due date of the milestone -+ `state_event` (optional) - The state event of the milestone (close|activate) - +- `id` (required) - The ID of a project +- `milestone_id` (required) - The ID of a project milestone +- `title` (optional) - The title of a milestone +- `description` (optional) - The description of a milestone +- `due_date` (optional) - The due date of the milestone +- `state_event` (optional) - The state event of the milestone (close|activate) diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 7a498272334..47c81b6446c 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -10,8 +10,7 @@ GET /projects/:id/snippets Parameters: -+ `id` (required) - The ID of a project - +- `id` (required) - The ID of a project ## Single snippet @@ -23,8 +22,8 @@ GET /projects/:id/snippets/:snippet_id Parameters: -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet +- `id` (required) - The ID of a project +- `snippet_id` (required) - The ID of a project's snippet ```json { @@ -45,7 +44,6 @@ Parameters: } ``` - ## Create new snippet Creates a new project snippet. The user must have permission to create new snippets. @@ -56,11 +54,10 @@ POST /projects/:id/snippets Parameters: -+ `id` (required) - The ID of a project -+ `title` (required) - The title of a snippet -+ `file_name` (required) - The name of a snippet file -+ `code` (required) - The content of a snippet - +- `id` (required) - The ID of a project +- `title` (required) - The title of a snippet +- `file_name` (required) - The name of a snippet file +- `code` (required) - The content of a snippet ## Update snippet @@ -72,12 +69,11 @@ PUT /projects/:id/snippets/:snippet_id Parameters: -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet -+ `title` (optional) - The title of a snippet -+ `file_name` (optional) - The name of a snippet file -+ `code` (optional) - The content of a snippet - +- `id` (required) - The ID of a project +- `snippet_id` (required) - The ID of a project's snippet +- `title` (optional) - The title of a snippet +- `file_name` (optional) - The name of a snippet file +- `code` (optional) - The content of a snippet ## Delete snippet @@ -90,9 +86,8 @@ DELETE /projects/:id/snippets/:snippet_id Parameters: -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet - +- `id` (required) - The ID of a project +- `snippet_id` (required) - The ID of a project's snippet ## Snippet content @@ -104,5 +99,5 @@ GET /projects/:id/snippets/:snippet_id/raw Parameters: -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet +- `id` (required) - The ID of a project +- `snippet_id` (required) - The ID of a project's snippet diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 820ae71361d..ae56b04b6ce 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -4,12 +4,11 @@ ## Create, read, update and delete repository files using this API -- - - +--- ## Get file from repository -Allows you to receive information about file in repository like name, size, content. -Note that file content is Base64 encoded. +Allows you to receive information about file in repository like name, size, content. Note that file content is Base64 encoded. ``` GET /projects/:id/repository/files @@ -32,8 +31,8 @@ Example response: Parameters: -+ `file_path` (required) - Full path to new file. Ex. lib/class.rb -+ `ref` (required) - The name of branch, tag or commit +- `file_path` (required) - Full path to new file. Ex. lib/class.rb +- `ref` (required) - The name of branch, tag or commit ## Create new file in repository @@ -52,11 +51,11 @@ Example response: Parameters: -+ `file_path` (required) - Full path to new file. Ex. lib/class.rb -+ `branch_name` (required) - The name of branch -+ `encoding` (optional) - 'text' or 'base64'. Text is default. -+ `content` (required) - File content -+ `commit_message` (required) - Commit message +- `file_path` (required) - Full path to new file. Ex. lib/class.rb +- `branch_name` (required) - The name of branch +- `encoding` (optional) - 'text' or 'base64'. Text is default. +- `content` (required) - File content +- `commit_message` (required) - Commit message ## Update existing file in repository @@ -75,11 +74,11 @@ Example response: Parameters: -+ `file_path` (required) - Full path to file. Ex. lib/class.rb -+ `branch_name` (required) - The name of branch -+ `encoding` (optional) - 'text' or 'base64'. Text is default. -+ `content` (required) - New file content -+ `commit_message` (required) - Commit message +- `file_path` (required) - Full path to file. Ex. lib/class.rb +- `branch_name` (required) - The name of branch +- `encoding` (optional) - 'text' or 'base64'. Text is default. +- `content` (required) - New file content +- `commit_message` (required) - Commit message ## Delete existing file in repository @@ -98,7 +97,6 @@ Example response: Parameters: -+ `file_path` (required) - Full path to file. Ex. lib/class.rb -+ `branch_name` (required) - The name of branch -+ `commit_message` (required) - Commit message - +- `file_path` (required) - Full path to file. Ex. lib/class.rb +- `branch_name` (required) - The name of branch +- `commit_message` (required) - Commit message diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 0d33aee2133..6483a73c7ec 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -2,7 +2,7 @@ All methods require admin authorization. -The url endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks). +The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks). ## List system hooks @@ -14,7 +14,7 @@ GET /hooks Parameters: -+ **none** +- **none** ```json [ @@ -34,8 +34,7 @@ POST /hooks Parameters: -+ `url` (required) - The hook URL - +- `url` (required) - The hook URL ## Test system hook @@ -45,7 +44,7 @@ GET /hooks/:id Parameters: -+ `id` (required) - The ID of hook +- `id` (required) - The ID of hook ```json { @@ -60,8 +59,7 @@ Parameters: ## Delete system hook -Deletes a system hook. This is an idempotent API function and returns `200 Ok` even if the hook -is not available. If the hook is deleted it is also returned as JSON. +Deletes a system hook. This is an idempotent API function and returns `200 Ok` even if the hook is not available. If the hook is deleted it is also returned as JSON. ``` DELETE /hooks/:id @@ -69,4 +67,4 @@ DELETE /hooks/:id Parameters: -+ `id` (required) - The ID of hook +- `id` (required) - The ID of hook diff --git a/doc/api/users.md b/doc/api/users.md index c185cf6478a..94af37629ff 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -3,6 +3,7 @@ ## List users Get a list of users. + This function takes pagination parameters `page` and `per_page` to restrict the list of users. ``` @@ -53,8 +54,7 @@ GET /users ] ``` -You can search for a users by email or username with: -`/users?search=John` +You can search for a users by email or username with: `/users?search=John` Also see `def search query` in `app/models/user.rb`. @@ -68,7 +68,7 @@ GET /users/:id Parameters: -+ `id` (required) - The ID of a user +- `id` (required) - The ID of a user ```json { @@ -93,7 +93,6 @@ Parameters: } ``` - ## User creation Creates a new user. Note only administrators can create new users. @@ -104,21 +103,20 @@ POST /users Parameters: -+ `email` (required) - Email -+ `password` (required) - Password -+ `username` (required) - Username -+ `name` (required) - Name -+ `skype` (optional) - Skype ID -+ `linkedin` (optional) - Linkedin -+ `twitter` (optional) - Twitter account -+ `website_url` (optional) - Website url -+ `projects_limit` (optional) - Number of projects user can create -+ `extern_uid` (optional) - External UID -+ `provider` (optional) - External provider name -+ `bio` (optional) - User's bio -+ `admin` (optional) - User is admin - true or false (default) -+ `can_create_group` (optional) - User can create groups - true or false - +- `email` (required) - Email +- `password` (required) - Password +- `username` (required) - Username +- `name` (required) - Name +- `skype` (optional) - Skype ID +- `linkedin` (optional) - Linkedin +- `twitter` (optional) - Twitter account +- `website_url` (optional) - Website url +- `projects_limit` (optional) - Number of projects user can create +- `extern_uid` (optional) - External UID +- `provider` (optional) - External provider name +- `bio` (optional) - User's bio +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false ## User modification @@ -130,30 +128,26 @@ PUT /users/:id Parameters: -+ `email` - Email -+ `username` - Username -+ `name` - Name -+ `password` - Password -+ `skype` - Skype ID -+ `linkedin` - Linkedin -+ `twitter` - Twitter account -+ `website_url` - Website url -+ `projects_limit` - Limit projects each user can create -+ `extern_uid` - External UID -+ `provider` - External provider name -+ `bio` - User's bio -+ `admin` (optional) - User is admin - true or false (default) -+ `can_create_group` (optional) - User can create groups - true or false - -Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would -be more appropriate, e.g. when renaming the email address to some existing one. - +- `email` - Email +- `username` - Username +- `name` - Name +- `password` - Password +- `skype` - Skype ID +- `linkedin` - Linkedin +- `twitter` - Twitter account +- `website_url` - Website url +- `projects_limit` - Limit projects each user can create +- `extern_uid` - External UID +- `provider` - External provider name +- `bio` - User's bio +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false + +Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. ## User deletion -Deletes a user. Available only for administrators. This is an idempotent function, calling this function -for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user -was actually deleted or not. In the former the user is returned and in the latter not. +Deletes a user. Available only for administrators. This is an idempotent function, calling this function for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user was actually deleted or not. In the former the user is returned and in the latter not. ``` DELETE /users/:id @@ -161,8 +155,7 @@ DELETE /users/:id Parameters: -+ `id` (required) - The ID of the user - +- `id` (required) - The ID of the user ## Current user @@ -194,7 +187,6 @@ GET /user } ``` - ## List SSH keys Get a list of currently authenticated user's SSH keys. @@ -220,7 +212,7 @@ GET /user/keys Parameters: -+ **none** +- **none** ## List SSH keys for user @@ -232,8 +224,7 @@ GET /users/:uid/keys Parameters: -+ `uid` (required) - id of specified user - +- `uid` (required) - id of specified user ## Single SSH key @@ -245,7 +236,7 @@ GET /user/keys/:id Parameters: -+ `id` (required) - The ID of an SSH key +- `id` (required) - The ID of an SSH key ```json { @@ -255,7 +246,6 @@ Parameters: } ``` - ## Add SSH key Creates a new key owned by the currently authenticated user. @@ -266,9 +256,8 @@ POST /user/keys Parameters: -+ `title` (required) - new SSH Key's title -+ `key` (required) - new SSH key - +- `title` (required) - new SSH Key's title +- `key` (required) - new SSH key ## Add SSH key for user @@ -280,17 +269,15 @@ POST /users/:id/keys Parameters: -+ `id` (required) - id of specified user -+ `title` (required) - new SSH Key's title -+ `key` (required) - new SSH key +- `id` (required) - id of specified user +- `title` (required) - new SSH Key's title +- `key` (required) - new SSH key -Will return created key with status `201 Created` on success, or `404 Not -found` on fail. +Will return created key with status `201 Created` on success, or `404 Not found` on fail. -## Delete SSH key +## Delete SSH key for current user -Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already -deleted or not available results in `200 Ok`. +Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already deleted or not available results in `200 Ok`. ``` DELETE /user/keys/:id @@ -298,9 +285,9 @@ DELETE /user/keys/:id Parameters: -+ `id` (required) - SSH key ID +- `id` (required) - SSH key ID -## Delete SSH key +## Delete SSH key for given user Deletes key owned by a specified user. Available only for admin. @@ -310,8 +297,7 @@ DELETE /users/:uid/keys/:id Parameters: -+ `uid` (required) - id of specified user -+ `id` (required) - SSH key ID +- `uid` (required) - id of specified user +- `id` (required) - SSH key ID Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found. - |