summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/api/README.md244
-rw-r--r--doc/api/branches.md108
-rw-r--r--doc/api/commits.md74
-rw-r--r--doc/api/deploy_key_multiple_projects.md18
-rw-r--r--doc/api/deploy_keys.md74
-rw-r--r--doc/api/groups.md714
-rw-r--r--doc/api/issues.md404
-rw-r--r--doc/api/keys.md72
-rw-r--r--doc/api/labels.md152
-rw-r--r--doc/api/namespaces.md29
-rw-r--r--doc/api/session.md42
-rw-r--r--doc/api/settings.md98
-rw-r--r--doc/api/system_hooks.md96
13 files changed, 1394 insertions, 731 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 2fa177ff4dd..51cd67f47f1 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -27,16 +27,15 @@
- [Build triggers](build_triggers.md)
- [Build Variables](build_variables.md)
-## Clients
-
-Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients).
-You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls.
-
-## Introduction
+## Authentication
-All API requests require authentication. You need to pass a `private_token` parameter by URL or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile.
+All API requests require authentication. You need to pass a `private_token`
+parameter by URL or header. If passed as a header, the header name must be
+**PRIVATE-TOKEN** (capital and with dash instead of underscore). You can find
+or reset your private token in your account page (`/profile/account`).
-If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
+If `private_token` is invalid or omitted, then an error message will be
+returned with status code `401`:
```json
{
@@ -44,71 +43,82 @@ If no, or an invalid, `private_token` is provided then an error message will be
}
```
-API requests should be prefixed with `api` and the API version. The API version is defined in `lib/api.rb`.
+API requests should be prefixed with `api` and the API version. The API version
+is defined in `lib/api.rb`.
Example of a valid API request:
-```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U
+```shell
+GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
```
-Example for a valid API request using curl and authentication via header:
+Example of a valid API request using curl and authentication via header:
-```
-curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.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.
## Authentication with OAuth2 token
-Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter.
+Instead of the `private_token` you can transmit the OAuth2 access token as a
+header or as a parameter.
-### OAuth2 token (as a parameter)
+Example of OAuth2 token as a parameter:
-```
-curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
+```shell
+curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN
```
-### OAuth2 token (as a header)
+Example of OAuth2 token as a header:
-```
-curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
+```shell
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user
```
Read more about [GitLab as an OAuth2 client](oauth2.md).
## 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.
-
-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.
-
-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
-- `422 Unprocessable` - The entity could not be processed
-- `500 Server Error` - While handling the request something went wrong on the server side
+The API is designed to return different status codes according to context and
+action. This way if a request results in an error, the caller is able to get
+insight into what went wrong.
+
+The following table gives an overview of how the API functions generally behave.
+
+| Request type | Explanation |
+| ------------ | ----------- |
+| `GET` | Access one or more resources and return the result as JSON. |
+| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
+| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
+| `DELETE` | Designed to be idempotent, meaning a request to 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 table shows the possible return codes for API requests.
+
+| Return values | Explanation |
+| ------------- | ----------- |
+| `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](#authentication) is necessary. |
+| `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. |
+| `422 Unprocessable` | The entity could not be processed. |
+| `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).
+All API requests support performing an API call as if you were another user,
+provided your private token is from an administration account. You need to pass
+the `sudo` parameter by URL or header with an ID or username of the user you
+want to perform the operation as. If passed as a 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:
+If a non administrative `private_token` is provided, then an error message will
+be returned with status code `403`:
```json
{
@@ -116,7 +126,8 @@ If a non administrative `private_token` is provided then an error message will b
}
```
-If the sudo user id or username cannot be found then an error message will be returned with status code 404:
+If the sudo user id or username cannot be found, an error message will be
+returned with status code `404`:
```json
{
@@ -124,94 +135,133 @@ If the sudo user id or username cannot be found then an error message will be re
}
```
-Example of a valid API with sudo request:
+Example of a valid API call with sudo request providing a username and an ID
+respectively:
-```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username
+```shell
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
```
-```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23
+```shell
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
```
-Example for a valid API request with sudo using curl and authentication via header:
+Example of 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"
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects"
```
-```
-curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects"
```
## Pagination
-When listing resources you can pass the following parameters:
+Sometimes the returned result will span across many lines. 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
+| Parameter | Description |
+| --------- | ----------- |
+| `page` | Page number (default: `1`). |
+| `per_page`| Number of items to list per page (default: `20`, max: `100`). |
-[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.
+In the example below, we list 50 [namespaces](namespaces.md) per page.
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50
+```
+
+[Link headers](http://www.w3.org/wiki/LinkHeader) are sent 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 entities: id and iid. The main difference between them is scope. Example:
+When you work with the API, you may notice two similar fields in API entities:
+`id` and `iid`. The main difference between them is scope.
+
+For example, an issue might have `id: 46` and `iid: 5`.
-Issue:
+| Parameter | Description |
+| --------- | ----------- |
+| id | is unique across all issues and is used for any API call. |
+| iid | is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see the `iid`. |
- id: 46
- iid: 5
+That means that if you want to get an issue via the API you should use:
+
+```bash
+https://gitlab.example.com/api/v3/projects/42/issues/:id.json
+```
-- id - is unique across all issues. It's used for any api call.
-- iid - is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see iid.
+On the other hand, if you want to create a link to a web page you should use:
-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`
+```bash
+https://gitlab.example.com/api/v3/projects/42/issues/:iid.json
+```
## Data validation and error reporting
-When working with the API you may encounter validation errors. In such case, the API will answer with an HTTP `400` status.
+When working with the API you may encounter validation errors. In such case,
+the API will answer with an HTTP `400` status.
+
Such errors appear in two cases:
-* A required attribute of the API request is missing, e.g. the title of an issue is not given
-* An attribute did not pass the validation, e.g. user bio is too long
+- A required attribute of the API request is missing, e.g. the title of an
+ issue is not given
+- An attribute did not pass the validation, e.g. user bio is too long
When an attribute is missing, you will get something like:
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
-
- {
- "message":"400 (Bad request) \"title\" not given"
- }
-
-When a validation error occurs, error messages will be different. They will hold all details of validation errors:
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message":"400 (Bad request) \"title\" not given"
+}
+```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
+When a validation error occurs, error messages will be different. They will
+hold all details of validation errors:
- {
- "message": {
- "bio": [
- "is too long (maximum is 255 characters)"
- ]
- }
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message": {
+ "bio": [
+ "is too long (maximum is 255 characters)"
+ ]
}
+}
+```
-This makes error messages more machine-readable. The format can be described as follow:
+This makes error messages more machine-readable. The format can be described as
+follows:
- {
- "message": {
+```json
+{
+ "message": {
+ "<property-name>": [
+ "<error-message>",
+ "<error-message>",
+ ...
+ ],
+ "<embed-entity>": {
"<property-name>": [
"<error-message>",
"<error-message>",
...
],
- "<embed-entity>": {
- "<property-name>": [
- "<error-message>",
- "<error-message>",
- ...
- ],
- }
}
}
+}
+```
+
+## Clients
+
+There are many unofficial GitLab API Clients for most of the popular
+programming languages. Visit the [GitLab website][] for a complete list.
+
+[GitLab website]: https://about.gitlab.com/applications/#api-clients
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 6a9c10c8520..abc4732c395 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically.
GET /projects/:id/repository/branches
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
-- `id` (required) - The ID of a project
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches
+```
+
+Example response:
```json
[
{
+ "name": "master",
+ "protected": true,
"commit": {
"author_email": "john@example.com",
"author_name": "John Smith",
@@ -27,10 +35,9 @@ Parameters:
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
- },
- "name": "master",
- "protected": true
- }
+ }
+ },
+ ...
]
```
@@ -42,13 +49,21 @@ Get a single project repository branch.
GET /projects/:id/repository/branches/:branch
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master
+```
+
+Example response:
```json
{
+ "name": "master",
+ "protected": true,
"commit": {
"author_email": "john@example.com",
"author_name": "John Smith",
@@ -61,25 +76,30 @@ Parameters:
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
- },
- "name": "master",
- "protected": true
+ }
}
```
## Protect repository branch
-Protects a single project repository branch. This is an idempotent function, protecting an already
-protected repository branch still returns a `200 OK` status code.
+Protects a single project repository branch. This is an idempotent function,
+protecting an already protected repository branch still returns a `200 OK`
+status code.
```
PUT /projects/:id/repository/branches/:branch/protect
```
-Parameters:
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/protect
+```
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
+
+Example response:
```json
{
@@ -103,17 +123,24 @@ Parameters:
## Unprotect repository branch
-Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
-unprotected repository branch still returns a `200 OK` status code.
+Unprotects a single project repository branch. This is an idempotent function,
+unprotecting an already unprotected repository branch still returns a `200 OK`
+status code.
```
PUT /projects/:id/repository/branches/:branch/unprotect
```
-Parameters:
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+Example response:
```json
{
@@ -141,11 +168,17 @@ Parameters:
POST /projects/:id/repository/branches
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch_name` | string | yes | The name of the branch |
+| `ref` | string | yes | The branch name or commit SHA to create branch from |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master"
+```
-- `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
+Example response:
```json
{
@@ -162,12 +195,13 @@ Parameters:
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
},
- "name": "master",
+ "name": "newbranch",
"protected": false
}
```
-It return 200 if succeed or 400 if failed with error message explaining reason.
+It returns `200` if it succeeds or `400` if failed with an error message
+explaining the reason.
## Delete repository branch
@@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason.
DELETE /projects/:id/repository/branches/:branch
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+It returns `200` if it succeeds, `404` if the branch to be deleted does not exist
+or `400` for other reasons. In case of an error, an explaining message is provided.
-It return 200 if succeed, 404 if the branch to be deleted does not exist
-or 400 for other reasons. In case of an error, an explaining message is provided.
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
+```
-Success response:
+Example response:
```json
{
- "branch_name": "my-removed-branch"
+ "branch_name": "newbranch"
}
```
diff --git a/doc/api/commits.md b/doc/api/commits.md
index 93d62b751e6..a07c9dff54e 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -8,10 +8,16 @@ Get a list of repository commits in a project.
GET /projects/:id/repository/commits
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `ref_name` | string | no | 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
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits"
+```
+
+Example response:
```json
[
@@ -48,8 +54,16 @@ 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
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master
+```
+
+Example response:
```json
{
@@ -79,8 +93,16 @@ 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
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/diff"
+```
+
+Example response:
```json
[
@@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments
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
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments"
+```
+
+Example response:
```json
[
@@ -128,20 +158,30 @@ Parameters:
## Post comment to commit
-Adds a comment to a commit. Optionally you can post comments on a specific line of a commit. Therefor both `path`, `line_new` and `line_old` are required.
+Adds a comment to a commit. Optionally you can post comments on a specific line
+of a commit. In that case `path`, `line` and `line_type` are required.
```
POST /projects/:id/repository/commits/:sha/comments
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+| `note` | string | yes | Text of comment |
+| `path` | string | no | The file path relative to the repository |
+| `line` | integer | no | The line number |
+| `line_type` | string | no | The line type. Takes `new` or `old` as arguments |
+
+In order to post a comment in a particular line of a particular file, you must
+specify `path`, `line` and `line_type` should be `new`.
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments?note=New%20comment&path=CHANGELOG&line=664&line_type=new"
+```
-- `id` (required) - The ID of a project
-- `sha` (required) - The name of a repository branch or tag or if not given the default branch
-- `note` (required) - Text of comment
-- `path` (optional) - The file path
-- `line` (optional) - The line number
-- `line_type` (optional) - The line type (new or old)
+Example response:
```json
{
diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md
index 1a5a458905e..3ad836f51b5 100644
--- a/doc/api/deploy_key_multiple_projects.md
+++ b/doc/api/deploy_key_multiple_projects.md
@@ -1,25 +1,29 @@
# Adding deploy keys to multiple projects
-If you want to easily add the same deploy key to multiple projects in the same group, this can be achieved quite easily with the API.
+If you want to easily add the same deploy key to multiple projects in the same
+group, this can be achieved quite easily with the API.
-First, find the ID of the projects you're interested in, by either listing all projects:
+First, find the ID of the projects you're interested in, by either listing all
+projects:
```
-curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/projects
+curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/projects
```
-Or finding the id of a group and then listing all projects in that group:
+Or finding the ID of a group and then listing all projects in that group:
```
-curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/groups
+curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/groups
# For group 1234:
-curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/groups/1234
+curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/groups/1234
```
With those IDs, add the same deploy key to all:
+
```
for project_id in 321 456 987; do
- curl -X POST --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/projects/${project_id}/keys
+ curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" \
+ --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v3/projects/${project_id}/keys
done
```
diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index e4492fc609c..9da1fe22e61 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -8,9 +8,15 @@ Get a list of a project's deploy keys.
GET /projects/:id/keys
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys"
+```
-- `id` (required) - The ID of the project
+Example response:
```json
[
@@ -39,8 +45,16 @@ GET /projects/:id/keys/:key_id
Parameters:
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `key_id` | integer | yes | The ID of the deploy key |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/11"
+```
+
+Example response:
```json
{
@@ -54,17 +68,34 @@ Parameters:
## 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
+
+If the deploy key already exists in another project, it will be joined to current
+project only if original one was is accessible by the same user.
```
POST /projects/:id/keys
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `title` | string | yes | New deploy key's title |
+| `key` | string | yes | New deploy key |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v3/projects/5/keys/"
+```
-- `id` (required) - The ID of the project
-- `title` (required) - New deploy key's title
-- `key` (required) - New deploy key
+Example response:
+
+```json
+{
+ "key" : "ssh-rsa AAAA...",
+ "id" : 12,
+ "title" : "My deploy key",
+ "created_at" : "2015-08-29T12:44:31.550Z"
+}
+```
## Delete deploy key
@@ -74,7 +105,26 @@ Delete a deploy key from a project
DELETE /projects/:id/keys/:key_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `key_id` | integer | yes | The ID of the deploy key |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/13"
+```
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+Example response:
+
+```json
+{
+ "updated_at" : "2015-08-29T12:50:57.259Z",
+ "key" : "ssh-rsa AAAA...",
+ "public" : false,
+ "title" : "My deploy key",
+ "user_id" : null,
+ "created_at" : "2015-08-29T12:50:57.259Z",
+ "fingerprint" : "6a:33:1f:74:51:c0:39:81:79:ec:7a:31:f8:40:20:43",
+ "id" : 13
+}
+```
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 808675d8605..928003310d0 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -1,256 +1,458 @@
-# Groups
-
-## List groups
-
-Get a list of groups. (As user: my groups, as admin: all groups)
-
-```
-GET /groups
-```
-
-```json
-[
- {
- "id": 1,
- "name": "Foobar Group",
- "path": "foo-bar",
- "description": "An interesting group"
- }
-]
-```
-
-You can search for groups by name or path, see below.
-
-
-## List a group's projects
-
-Get a list of projects in this group.
-
-```
-GET /groups/:id/projects
-```
-
-Parameters:
-
-- `archived` (optional) - if passed, limit by archived status
-- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
-- `search` (optional) - Return list of authorized projects according to a search criteria
-- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first
-
-```json
-[
- {
- "id": 4,
- "description": null,
- "default_branch": "master",
- "public": false,
- "visibility_level": 0,
- "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
- "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
- "web_url": "http://example.com/diaspora/diaspora-client",
- "tag_list": [
- "example",
- "disapora client"
- ],
- "owner": {
- "id": 3,
- "name": "Diaspora",
- "created_at": "2013-09-30T13: 46: 02Z"
- },
- "name": "Diaspora Client",
- "name_with_namespace": "Diaspora / Diaspora Client",
- "path": "diaspora-client",
- "path_with_namespace": "diaspora/diaspora-client",
- "issues_enabled": true,
- "merge_requests_enabled": true,
- "builds_enabled": true,
- "wiki_enabled": true,
- "snippets_enabled": false,
- "created_at": "2013-09-30T13: 46: 02Z",
- "last_activity_at": "2013-09-30T13: 46: 02Z",
- "creator_id": 3,
- "namespace": {
- "created_at": "2013-09-30T13: 46: 02Z",
- "description": "",
- "id": 3,
- "name": "Diaspora",
- "owner_id": 1,
- "path": "diaspora",
- "updated_at": "2013-09-30T13: 46: 02Z"
- },
- "archived": false,
- "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png"
- }
-]
-```
-
-## Details of a group
-
-Get all details of a group.
-
-```
-GET /groups/:id
-```
-
-Parameters:
-
-- `id` (required) - The ID or path of a group
-
-## New group
-
-Creates a new project group. Available only for users who can create groups.
-
-```
-POST /groups
-```
-
-Parameters:
-
-- `name` (required) - The name of the group
-- `path` (required) - The path of the group
-- `description` (optional) - The group's description
-
-## Transfer project to group
-
-Transfer a project to the Group namespace. Available only for admin
-
-```
-POST /groups/:id/projects/:project_id
-```
-
-Parameters:
-
-- `id` (required) - The ID or path of a group
-- `project_id` (required) - The ID of a project
-
-## Remove group
-
-Removes group with all projects inside.
-
-```
-DELETE /groups/:id
-```
-
-Parameters:
-
-- `id` (required) - The ID or path of a user group
-
-## Search for group
-
-Get all groups that match your string in their name or path.
-
-```
-GET /groups?search=foobar
-```
-
-```json
-[
- {
- "id": 1,
- "name": "Foobar Group",
- "path": "foo-bar",
- "description": "An interesting group"
- }
-]
-```
-
-## Group members
-
-**Group access levels**
-
-The group access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized:
-
-```
-GUEST = 10
-REPORTER = 20
-DEVELOPER = 30
-MASTER = 40
-OWNER = 50
-```
-
-### List group members
-
-Get a list of group members viewable by the authenticated user.
-
-```
-GET /groups/:id/members
-```
-
-```json
-[
- {
- "id": 1,
- "username": "raymond_smith",
- "email": "ray@smith.org",
- "name": "Raymond Smith",
- "state": "active",
- "created_at": "2012-10-22T14:13:35Z",
- "access_level": 30
- },
- {
- "id": 2,
- "username": "john_doe",
- "email": "joh@doe.org",
- "name": "John Doe",
- "state": "active",
- "created_at": "2012-10-22T14:13:35Z",
- "access_level": 30
- }
-]
-```
-
-### Add group member
-
-Adds a user to the list of group members.
-
-```
-POST /groups/:id/members
-```
-
-Parameters:
-
-- `id` (required) - The ID or path of a group
-- `user_id` (required) - The ID of a user to add
-- `access_level` (required) - Project access level
-
-### Edit group team member
-
-Updates a group team member to a specified access level.
-
-```
-PUT /groups/:id/members/:user_id
-```
-
-Parameters:
-
-- `id` (required) - The ID of a group
-- `user_id` (required) - The ID of a group member
-- `access_level` (required) - Project access level
-
-### Remove user team member
-
-Removes user from user team.
-
-```
-DELETE /groups/:id/members/:user_id
-```
-
-Parameters:
-
-- `id` (required) - The ID or path of a user group
-- `user_id` (required) - The ID of a group member
-
-## Namespaces in groups
-
-By default, groups only get 20 namespaces at a time because the API results are paginated.
-
-To get more (up to 100), pass the following as an argument to the API call:
-```
-/groups?per_page=100
-```
-
-And to switch pages add:
-```
-/groups?per_page=100&page=2
-```
+# Groups
+
+Every API call to groups must be authenticated.
+
+If a user is not a member of a group and the group contains at least one private
+project, all API calls return a 403 status code.
+
+Groups use [pagination](README.md#pagination).
+
+## List groups
+
+Get a list of a user's groups. Administrators get a list of all groups.
+
+```
+GET /groups
+```
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups
+```
+
+Example response:
+
+```json
+[
+ {
+ "id" : 3,
+ "name" : "Gitlab Org",
+ "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+ "path" : "gitlab-org",
+ "avatar_url" : null,
+ "web_url" : "http://gitlab.example.com/groups/gitlab-org"
+ },
+]
+```
+
+## List a group's projects
+
+Get a list of projects in this group.
+
+```
+GET /groups/:id/projects
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID or path of a group |
+| `archived`| boolean | no | If passed, limit by archived status |
+| `order_by`| string | no | Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` |
+| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`
+| `search` | string | no | Return list of authorized projects according to a search criteria
+| `ci_enabled_first` | - | no | Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/4/projects
+```
+
+Example response:
+
+```json
+[
+ {
+ "id": 4,
+ "description": null,
+ "default_branch": "master",
+ "public": false,
+ "visibility_level": 0,
+ "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
+ "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
+ "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
+ "tag_list": [
+ "example",
+ "disapora client"
+ ],
+ "owner": {
+ "id": 3,
+ "name": "Diaspora",
+ "created_at": "2013-09-30T13: 46: 02Z"
+ },
+ "name": "Diaspora Client",
+ "name_with_namespace": "Diaspora / Diaspora Client",
+ "path": "diaspora-client",
+ "path_with_namespace": "diaspora/diaspora-client",
+ "issues_enabled": true,
+ "merge_requests_enabled": true,
+ "builds_enabled": true,
+ "wiki_enabled": true,
+ "snippets_enabled": false,
+ "created_at": "2013-09-30T13: 46: 02Z",
+ "last_activity_at": "2013-09-30T13: 46: 02Z",
+ "creator_id": 3,
+ "namespace": {
+ "created_at": "2013-09-30T13: 46: 02Z",
+ "description": "",
+ "id": 3,
+ "name": "Diaspora",
+ "owner_id": 1,
+ "path": "diaspora",
+ "updated_at": "2013-09-30T13: 46: 02Z"
+ },
+ "archived": false,
+ "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png"
+ }
+]
+```
+
+## Details of a group
+
+Get all details of a group by searching by name or by path.
+
+Every authenticated user can see the details of a group if there are no private
+projects in it.
+
+```
+GET /groups/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID or path of a group |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/3
+```
+
+Example response:
+
+```json
+[
+{
+ "web_url" : "http://gitlab.example.com/groups/gitlab-org",
+ "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+ "name" : "Gitlab Org",
+ "avatar_url" : null,
+ "path" : "gitlab-org",
+ "id" : 3,
+ "projects" : [
+ {
+ "tag_list" : [],
+ "path" : "gitlab-test",
+ "forks_count" : 0,
+ "default_branch" : "master",
+ "wiki_enabled" : true,
+ "last_activity_at" : "2015-09-15T18:34:17.834Z",
+ "http_url_to_repo" : "http://gitlab.example.com/gitlab-org/gitlab-test.git",
+ "archived" : false,
+ "id" : 5,
+ "star_count" : 0,
+ "avatar_url" : null,
+ "path_with_namespace" : "gitlab-org/gitlab-test",
+ "web_url" : "http://gitlab.example.com/gitlab-org/gitlab-test",
+ "merge_requests_enabled" : true,
+ "name_with_namespace" : "Gitlab Org / Gitlab Test",
+ "creator_id" : 1,
+ "snippets_enabled" : false,
+ "public" : true,
+ "issues_enabled" : true,
+ "namespace" : {
+ "avatar" : {
+ "url" : null
+ },
+ "owner_id" : null,
+ "path" : "gitlab-org",
+ "name" : "Gitlab Org",
+ "created_at" : "2015-09-15T18:24:44.162Z",
+ "updated_at" : "2015-09-15T18:24:44.162Z",
+ "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+ "id" : 3
+ },
+ "name" : "Gitlab Test",
+ "created_at" : "2015-09-15T18:27:31.969Z",
+ "ssh_url_to_repo" : "axil@gitlab.example.com:gitlab-org/gitlab-test.git",
+ "visibility_level" : 20,
+ "description" : "Veritatis harum culpa perferendis odit voluptates vel et."
+ },
+]
+```
+
+## New group
+
+Creates a new group. Available only for users who can create groups.
+
+```
+POST /groups
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `name` | string | yes | The name of the group |
+| `path` | string | yes | The path of the group |
+| `description` | string | no | The group's description |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups?path=my-group&name=My%20group"
+```
+
+Example response:
+
+```json
+{
+ "web_url" : "https://gitlab.example.com/groups/my-group",
+ "id" : 33,
+ "avatar_url" : null,
+ "description" : "",
+ "name" : "My group",
+ "path" : "my-group"
+}
+```
+
+## Transfer project to group
+
+Transfer a project to a Group namespace. Available only for admins.
+
+```
+POST /groups/:id/projects/:project_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a group |
+| `project_id` | integer | yes | The ID of a project |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/2/projects/9
+```
+
+Example response:
+
+```json
+{
+ "owner_id" : null,
+ "path" : "gitlab-org",
+ "created_at" : "2015-09-15T18:24:44.162Z",
+ "avatar" : {
+ "url" : null
+ },
+ "updated_at" : "2015-09-15T18:24:44.162Z",
+ "id" : 3,
+ "description" : "Quae magnam libero provident non illum quidem vel fugit.",
+ "name" : "Gitlab Org"
+}
+```
+
+## Remove group
+
+Removes a group and all its projects.
+
+```
+DELETE /groups/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or path of a group |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/my-group
+```
+
+Example response:
+
+```json
+{
+ "avatar" : {
+ "url" : null
+ },
+ "created_at" : "2015-10-29T12:29:50.407Z",
+ "updated_at" : "2015-10-29T12:29:50.407Z",
+ "description" : "",
+ "path" : "my-group",
+ "name" : "My group",
+ "id" : 33,
+ "owner_id" : null
+}
+```
+
+## Search for group
+
+Get all groups that match a string in their name or path.
+
+```
+GET /groups?search=foobar
+```
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups?search=gitlab"
+```
+
+Example response:
+
+```json
+[
+ {
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/groups/gitlab-org",
+ "path" : "gitlab-org",
+ "name" : "Gitlab Org",
+ "id" : 3,
+ "description" : "Quae magnam libero provident non illum quidem vel fugit."
+ }
+]
+```
+
+## Group members
+
+**Group access levels**
+
+The group access levels are defined in the `Gitlab::Access` module. Currently,
+these levels are recognized:
+
+```
+GUEST = 10
+REPORTER = 20
+DEVELOPER = 30
+MASTER = 40
+OWNER = 50
+```
+
+### List group members
+
+Get a list of group members viewable by the authenticated user.
+
+```
+GET /groups/:id/members
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a group |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/3/members
+```
+
+Example response:
+
+```json
+[
+ {
+ "username" : "peyton",
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/u/peyton",
+ "state" : "active",
+ "id" : 11,
+ "name" : "Sarai Walter",
+ "access_level" : 20
+ },
+ {
+ "access_level" : 20,
+ "name" : "Mallie Jacobs",
+ "id" : 5,
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/hazle",
+ "avatar_url" : null,
+ "username" : "hazle"
+ },
+]
+```
+
+### Add group member
+
+Adds a user to the list of group members.
+
+```
+POST /groups/:id/members
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+| `access_level` | integer | yes | The access level a user will have |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members?user_id=7&access_level=30"
+```
+
+Example response:
+
+```json
+{
+ "web_url" : "https://gitlab.example.com/u/laurine",
+ "username" : "laurine",
+ "state" : "active",
+ "id" : 7,
+ "access_level" : 30,
+ "name" : "Dr. Meta Fritsch",
+ "avatar_url" : null
+}
+```
+
+### Edit group member
+
+Updates a group team member to a specified access level.
+
+```
+PUT /groups/:id/members/:user_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+| `access_level` | integer | yes | The group access level a user will have |
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members/7?access_level=20"
+```
+
+Example response:
+
+```json
+{
+ "web_url" : "https://gitlab.example.com/u/laurine",
+ "username" : "laurine",
+ "state" : "active",
+ "id" : 7,
+ "access_level" : 20,
+ "name" : "Dr. Meta Fritsch",
+ "avatar_url" : null
+}
+```
+
+### Remove user from group
+
+Removes a user from a group.
+
+```
+DELETE /groups/:id/members/:user_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a group |
+| `user_id` | integer | yes | The ID of a user to add |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/groups/3/members/7"
+```
+
+Example response:
+
+```json
+{
+ "source_type" : "Namespace",
+ "invite_accepted_at" : null,
+ "updated_at" : "2015-10-29T15:11:59.687Z",
+ "notification_level" : 3,
+ "id" : 60,
+ "invite_token" : null,
+ "access_level" : 10,
+ "created_at" : "2015-10-29T15:02:39.659Z",
+ "created_by_id" : 26,
+ "invite_email" : null,
+ "user_id" : 7,
+ "source_id" : 3
+}
+```
diff --git a/doc/api/issues.md b/doc/api/issues.md
index d407bc35d79..9e704648b25 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,9 +1,20 @@
# Issues
+Every API call to issues must be authenticated.
+
+If a user is not a member of a project and the project is private, a `GET`
+request on that project will result to a `404` status code.
+
+## Issues pagination
+
+By default, `GET` requests return 20 results at a time because the API results
+are paginated.
+
+Read more on [pagination](README.md#pagination).
+
## List issues
-Get all issues created by authenticated user. This function takes pagination parameters
-`page` and `per_page` to restrict the list of issues.
+Get all issues created by the authenticated user.
```
GET /issues
@@ -14,81 +25,65 @@ GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
+| `labels` | string | no | Comma-separated list of label names |
+| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
+| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/issues
+```
-- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
-- `labels` (optional) - Comma-separated list of label names
-- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+Example response:
```json
[
- {
- "id": 43,
- "iid": 3,
- "project_id": 8,
- "title": "4xx/5xx pages",
- "description": "",
- "labels": [],
- "milestone": null,
- "assignee": null,
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "closed",
- "updated_at": "2012-07-02T17:53:12Z",
- "created_at": "2012-07-02T17:53:12Z"
- },
- {
- "id": 42,
- "iid": 4,
- "project_id": 8,
- "title": "Add user settings",
- "description": "",
- "labels": [
- "feature"
- ],
- "milestone": {
- "id": 1,
- "title": "v1.0",
- "description": "",
- "due_date": "2012-07-20",
- "state": "reopened",
- "updated_at": "2012-07-04T13:42:48Z",
- "created_at": "2012-07-04T13:42:48Z"
- },
- "assignee": {
- "id": 2,
- "username": "jack_smith",
- "email": "jack@example.com",
- "name": "Jack Smith",
- "state": "active",
- "created_at": "2012-05-23T08:01:01Z"
- },
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "opened",
- "updated_at": "2012-07-12T13:43:19Z",
- "created_at": "2012-06-28T12:58:06Z"
- }
+ {
+ "state" : "opened",
+ "description" : "Ratione dolores corrupti mollitia soluta quia.",
+ "author" : {
+ "state" : "active",
+ "id" : 18,
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe",
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "username" : "eileen.lowe"
+ },
+ "milestone" : {
+ "project_id" : 1,
+ "description" : "Ducimus nam enim ex consequatur cumque ratione.",
+ "state" : "closed",
+ "due_date" : null,
+ "iid" : 2,
+ "created_at" : "2016-01-04T15:31:39.996Z",
+ "title" : "v4.0",
+ "id" : 17,
+ "updated_at" : "2016-01-04T15:31:39.996Z"
+ },
+ "project_id" : 1,
+ "assignee" : {
+ "state" : "active",
+ "id" : 1,
+ "name" : "Administrator",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root"
+ },
+ "updated_at" : "2016-01-04T15:31:51.081Z",
+ "id" : 76,
+ "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
+ "created_at" : "2016-01-04T15:31:51.081Z",
+ "iid" : 6,
+ "labels" : []
+ },
]
```
## List project issues
-Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
-to return the list of project issues.
+Get a list of a project's issues.
```
GET /projects/:id/issues
@@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened
GET /projects/:id/issues?iid=42
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `iid` | integer | no | Return the issue having the given `iid` |
+| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
+| `labels` | string | no | Comma-separated list of label names |
+| `milestone` | string| no | The milestone title |
+| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
+| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
+
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues
+```
+
+Example response:
-- `id` (required) - The ID of a project
-- `iid` (optional) - Return the issue having the given `iid`
-- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
-- `labels` (optional) - Comma-separated list of label names
-- `milestone` (optional) - Milestone title
-- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+```json
+[
+ {
+ "project_id" : 4,
+ "milestone" : {
+ "due_date" : null,
+ "project_id" : 4,
+ "state" : "closed",
+ "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+ "iid" : 3,
+ "id" : 11,
+ "title" : "v3.0",
+ "created_at" : "2016-01-04T15:31:39.788Z",
+ "updated_at" : "2016-01-04T15:31:39.788Z"
+ },
+ "author" : {
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root",
+ "id" : 1,
+ "name" : "Administrator"
+ },
+ "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+ "state" : "closed",
+ "iid" : 1,
+ "assignee" : {
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/u/lennie",
+ "state" : "active",
+ "username" : "lennie",
+ "id" : 9,
+ "name" : "Dr. Luella Kovacek"
+ },
+ "labels" : [],
+ "id" : 41,
+ "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+ "updated_at" : "2016-01-04T15:31:46.176Z",
+ "created_at" : "2016-01-04T15:31:46.176Z"
+ }
+]
+```
## Single issue
-Gets a single project issue.
+Get a single project issue.
```
GET /projects/:id/issues/:issue_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `issue_id`| integer | yes | The ID of a project's issue |
-- `id` (required) - The ID of a project
-- `issue_id` (required) - The ID of a project issue
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41
+```
+
+Example response:
```json
{
- "id": 42,
- "iid": 3,
- "project_id": 8,
- "title": "Add user settings",
- "description": "",
- "labels": [
- "feature"
- ],
- "milestone": {
- "id": 1,
- "title": "v1.0",
- "description": "",
- "due_date": "2012-07-20",
- "state": "closed",
- "updated_at": "2012-07-04T13:42:48Z",
- "created_at": "2012-07-04T13:42:48Z"
- },
- "assignee": {
- "id": 2,
- "username": "jack_smith",
- "email": "jack@example.com",
- "name": "Jack Smith",
- "state": "active",
- "created_at": "2012-05-23T08:01:01Z"
- },
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "opened",
- "updated_at": "2012-07-12T13:43:19Z",
- "created_at": "2012-06-28T12:58:06Z"
+ "project_id" : 4,
+ "milestone" : {
+ "due_date" : null,
+ "project_id" : 4,
+ "state" : "closed",
+ "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+ "iid" : 3,
+ "id" : 11,
+ "title" : "v3.0",
+ "created_at" : "2016-01-04T15:31:39.788Z",
+ "updated_at" : "2016-01-04T15:31:39.788Z"
+ },
+ "author" : {
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root",
+ "id" : 1,
+ "name" : "Administrator"
+ },
+ "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+ "state" : "closed",
+ "iid" : 1,
+ "assignee" : {
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/u/lennie",
+ "state" : "active",
+ "username" : "lennie",
+ "id" : 9,
+ "name" : "Dr. Luella Kovacek"
+ },
+ "labels" : [],
+ "id" : 41,
+ "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+ "updated_at" : "2016-01-04T15:31:46.176Z",
+ "created_at" : "2016-01-04T15:31:46.176Z"
}
```
@@ -170,57 +221,122 @@ Parameters:
Creates a new project issue.
+If the operation is successful, a status code of `200` and the newly-created
+issue is returned. If an error occurs, an error number and a message explaining
+the reason is returned.
+
```
POST /projects/:id/issues
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `title` | string | yes | The title of an issue |
+| `description` | string | no | The description of an issue |
+| `assignee_id` | integer | no | The ID of a user to assign issue |
+| `milestone_id` | integer | no | The ID of a milestone to assign issue |
+| `labels` | string | no | Comma-separated label names for an issue |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug
+```
-- `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
+Example response:
-If the operation is successful, 200 and the newly created issue is returned.
-If an error occurs, an error number and a message explaining the reason is returned.
+```json
+{
+ "project_id" : 4,
+ "id" : 84,
+ "created_at" : "2016-01-07T12:44:33.959Z",
+ "iid" : 14,
+ "title" : "Issues with auth",
+ "state" : "opened",
+ "assignee" : null,
+ "labels" : [
+ "bug"
+ ],
+ "author" : {
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe",
+ "id" : 18,
+ "username" : "eileen.lowe"
+ },
+ "description" : null,
+ "updated_at" : "2016-01-07T12:44:33.959Z",
+ "milestone" : null
+}
+```
## Edit issue
-Updates an existing project issue. This function is also used to mark an issue as closed.
+Updates an existing project issue. This call is also used to mark an issue as
+closed.
+
+If the operation is successful, a code of `200` and the updated issue is
+returned. If an error occurs, an error number and a message explaining the
+reason is returned.
```
PUT /projects/:id/issues/:issue_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+| `title` | string | no | The title of an issue |
+| `description` | string | no | The description of an issue |
+| `assignee_id` | integer | no | The ID of a user to assign the issue to |
+| `milestone_id` | integer | no | The ID of a milestone to assign the issue to |
+| `labels` | string | no | Comma-separated label names for an issue |
+| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it |
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/85?state_event=close
+```
-- `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)
+Example response:
-If the operation is successful, 200 and the updated issue is returned.
-If an error occurs, an error number and a message explaining the reason is returned.
+```json
+{
+ "created_at" : "2016-01-07T12:46:01.410Z",
+ "author" : {
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "username" : "eileen.lowe",
+ "id" : 18,
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe"
+ },
+ "state" : "closed",
+ "title" : "Issues with auth",
+ "project_id" : 4,
+ "description" : null,
+ "updated_at" : "2016-01-07T12:55:16.213Z",
+ "iid" : 15,
+ "labels" : [
+ "bug"
+ ],
+ "id" : 85,
+ "assignee" : null,
+ "milestone" : null
+}
+```
## 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 `state_event` set to `close`.
+This call 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 the parameter `state_event` set to
+`close`. See [edit issue](#edit-issue) for more details.
```
DELETE /projects/:id/issues/:issue_id
```
-Parameters:
-
-- `id` (required) - The project ID
-- `issue_id` (required) - The ID of the issue
-
## Comments on issues
-Comments are done via the notes resource.
+Comments are done via the [notes](notes.md) resource.
diff --git a/doc/api/keys.md b/doc/api/keys.md
index faa6f212b43..80b5d644e59 100644
--- a/doc/api/keys.md
+++ b/doc/api/keys.md
@@ -2,45 +2,55 @@
## Get SSH key with user by ID of an SSH key
-Get SSH key with user by ID of an SSH key. Note only administrators can lookup SSH key with user by ID of an SSH key.
+Get the public SSH key with its user information by providing the ID of an SSH
+key.
+
+**Note**: This API call can be made only by administrators.
```
GET /keys/:id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of an SSH key |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/keys/1
+```
-- `id` (required) - The ID of an SSH key
+Example response:
```json
{
- "id": 1,
- "title": "Sample key 25",
- "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
- "created_at": "2015-09-03T07:24:44.627Z",
- "user": {
- "name": "John Smith",
- "username": "john_smith",
- "id": 25,
- "state": "active",
- "avatar_url": "http://www.gravatar.com/avatar/cfa35b8cd2ec278026357769582fa563?s=40\u0026d=identicon",
- "web_url": "http://localhost:3000/u/john_smith",
- "created_at": "2015-09-03T07:24:01.670Z",
- "is_admin": false,
- "bio": null,
- "skype": "",
- "linkedin": "",
- "twitter": "",
- "website_url": "",
- "email": "john@example.com",
- "theme_id": 2,
- "color_scheme_id": 1,
- "projects_limit": 10,
- "current_sign_in_at": null,
- "identities": [],
- "can_create_group": true,
- "can_create_project": true,
- "two_factor_enabled": false
- }
+ "created_at" : "2015-09-15T18:29:11.737Z",
+ "id" : 1,
+ "title" : "Sample key 25",
+ "user" : {
+ "username" : "user5",
+ "web_url" : "https://gitlab.example.com/u/user5",
+ "current_sign_in_at" : null,
+ "projects_limit" : 10,
+ "email" : "user5@example.com",
+ "name" : "User 5",
+ "identities" : [],
+ "theme_id" : 2,
+ "created_at" : "2015-09-15T18:28:19.510Z",
+ "can_create_project" : true,
+ "avatar_url" : null,
+ "can_create_group" : true,
+ "id" : 25,
+ "linkedin" : "",
+ "skype" : "",
+ "is_admin" : false,
+ "bio" : null,
+ "state" : "active",
+ "website_url" : "",
+ "color_scheme_id" : 1,
+ "twitter" : "",
+ "two_factor_enabled" : false
+ },
+ "key" : "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK
+2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
}
```
diff --git a/doc/api/labels.md b/doc/api/labels.md
index de41f35d284..6496ffe9fd1 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -2,83 +2,153 @@
## List labels
-Get all labels for given project.
+Get all labels for a given project.
```
GET /projects/:id/labels
```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels
+```
+
+Example response:
+
```json
[
- {
- "name": "Awesome",
- "color": "#DD10AA"
- },
- {
- "name": "Documentation",
- "color": "#1E80DD"
- },
- {
- "name": "Feature",
- "color": "#11FF22"
- },
- {
- "name": "Bug",
- "color": "#EE1122"
- }
+ {
+ "name" : "bug",
+ "color" : "#d9534f"
+ },
+ {
+ "color" : "#d9534f",
+ "name" : "confirmed"
+ },
+ {
+ "name" : "critical",
+ "color" : "#d9534f"
+ },
+ {
+ "color" : "#428bca",
+ "name" : "discussion"
+ },
+ {
+ "name" : "documentation",
+ "color" : "#f0ad4e"
+ },
+ {
+ "color" : "#5cb85c",
+ "name" : "enhancement"
+ },
+ {
+ "color" : "#428bca",
+ "name" : "suggestion"
+ },
+ {
+ "color" : "#f0ad4e",
+ "name" : "support"
+ }
]
```
## Create a new label
-Creates a new label for given repository with given name and color.
+Creates a new label for the given repository with the given name and color.
+
+It returns 200 if the label was successfully created, 400 for wrong parameters
+and 409 if the label already exists.
```
POST /projects/:id/labels
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the label |
+| `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the label
-- `color` (required) - Color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+Example response:
-It returns 200 and the newly created label, if the operation succeeds.
-If the label already exists, 409 and an error message is returned.
-If label parameters are invalid, 400 and an explaining error message is returned.
+```json
+{
+ "name" : "feature",
+ "color" : "#5843AD"
+}
+```
## Delete a label
-Deletes a label given by its name.
+Deletes a label with a given name.
+
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
```
DELETE /projects/:id/labels
```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the label to be deleted
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the label |
-It returns 200 if the label successfully was deleted, 400 for wrong parameters
-and 404 if the label does not exist.
-In case of an error, additionally an error message is returned.
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
+```
+
+Example response:
+
+```json
+{
+ "title" : "feature",
+ "color" : "#5843AD",
+ "updated_at" : "2015-11-03T21:22:30.737Z",
+ "template" : false,
+ "project_id" : 1,
+ "created_at" : "2015-11-03T21:22:30.737Z",
+ "id" : 9
+}
+```
## Edit an existing label
-Updates an existing label with new name or now color. At least one parameter
+Updates an existing label with new name or new color. At least one parameter
is required, to update the label.
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
+
```
PUT /projects/:id/labels
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the existing label |
+| `new_name` | string | yes if `color` if not provided | The new name of the label |
+| `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the existing label
-- `new_name` (optional) - The new name of the label
-- `color` (optional) - New color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+Example response:
-On success, this method returns 200 with the updated label.
-If required parameters are missing or parameters are invalid, 400 is returned.
-If the label to be updated is missing, 404 is returned.
-In case of an error, additionally an error message is returned.
+```json
+{
+ "color" : "#8E44AD",
+ "name" : "docs"
+}
+```
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index 7b3238441f6..68ed8bd3152 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -1,13 +1,22 @@
# Namespaces
+Namespaces account for usernames and groupnames.
+
+[Pagination](README.md#pagination) is used.
+
## List namespaces
-Get a list of namespaces. (As user: my namespaces, as admin: all namespaces)
+Get a list of namespaces. As a user, your namespaces are listed whereas if you
+are an administrator you get a list of all namespaces in the GitLab instance.
```
GET /namespaces
```
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces
+```
+
```json
[
{
@@ -23,22 +32,28 @@ GET /namespaces
]
```
-You can search for namespaces by name or path, see below.
-
## Search for namespace
-Get all namespaces that match your string in their name or path.
+Get all namespaces that match a string in their name or path.
```
GET /namespaces?search=foobar
```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `search` | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter
+```
+
```json
[
{
- "id": 1,
- "path": "user1",
- "kind": "user"
+ "id": 4,
+ "path": "twitter",
+ "kind": "group"
}
]
```
diff --git a/doc/api/session.md b/doc/api/session.md
index 47c1c8a7a49..71e93d0bb0a 100644
--- a/doc/api/session.md
+++ b/doc/api/session.md
@@ -1,39 +1,47 @@
# Session
-Login to get private token
+You can login with both GitLab and LDAP credentials in order to obtain the
+private token.
```
POST /session
```
-Parameters:
+| Attribute | Type | Required | Description |
+| ---------- | ------- | -------- | -------- |
+| `login` | string | yes | The username of the user|
+| `email` | string | yes if login is not provided | The email of the user |
+| `password` | string | yes | The password of the user |
-- `login` (required) - The login of user
-- `email` (required if login missing) - The email of user
-- `password` (required) - Valid password
-
-**You can login with both GitLab and LDAP credentials now**
+```bash
+curl -X POST "https://gitlab.example.com/api/v3/session?login=john_smith&password=strongpassw0rd"
+```
+Example response:
```json
{
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
"name": "John Smith",
- "private_token": "dd34asd13as",
- "blocked": false,
- "created_at": "2012-05-23T08:00:58Z",
+ "username": "john_smith",
+ "id": 32,
+ "state": "active",
+ "avatar_url": null,
+ "created_at": "2015-01-29T21:07:19.440Z",
+ "is_admin": true,
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
- "dark_scheme": false,
+ "email": "john@example.com",
"theme_id": 1,
- "is_admin": false,
+ "color_scheme_id": 1,
+ "projects_limit": 10,
+ "current_sign_in_at": "2015-07-07T07:10:58.392Z",
+ "identities": [],
"can_create_group": true,
- "can_create_team": true,
- "can_create_project": true
+ "can_create_project": true,
+ "two_factor_enabled": false,
+ "private_token": "9koXpg98eAheJpvBs5tK"
}
```
diff --git a/doc/api/settings.md b/doc/api/settings.md
index 96867c67915..001de76c7af 100644
--- a/doc/api/settings.md
+++ b/doc/api/settings.md
@@ -1,67 +1,77 @@
# Application settings
-This API allows you to read and modify GitLab instance application settings.
+These API calls allow you to read and modify GitLab instance application
+settings as appear in `/admin/application_settings`. You have to be an
+administrator in order to perform this action.
+## Get current application settings
-## Get current application settings:
+List the current application settings of the GitLab instance.
```
GET /application/settings
```
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings
+```
+
+Example response:
+
```json
{
- "id": 1,
- "default_projects_limit": 10,
- "signup_enabled": true,
- "signin_enabled": true,
- "gravatar_enabled": true,
- "sign_in_text": "",
- "created_at": "2015-06-12T15:51:55.432Z",
- "updated_at": "2015-06-30T13:22:42.210Z",
- "home_page_url": "",
- "default_branch_protection": 2,
- "twitter_sharing_enabled": true,
- "restricted_visibility_levels": [],
- "max_attachment_size": 10,
- "session_expire_delay": 10080,
- "default_project_visibility": 0,
- "default_snippet_visibility": 0,
- "restricted_signup_domains": [],
- "user_oauth_applications": true,
- "after_sign_out_path": ""
+ "default_projects_limit" : 10,
+ "signup_enabled" : true,
+ "id" : 1,
+ "default_branch_protection" : 2,
+ "restricted_visibility_levels" : [],
+ "signin_enabled" : true,
+ "twitter_sharing_enabled" : true,
+ "after_sign_out_path" : null,
+ "max_attachment_size" : 10,
+ "user_oauth_applications" : true,
+ "updated_at" : "2016-01-04T15:44:55.176Z",
+ "session_expire_delay" : 10080,
+ "home_page_url" : null,
+ "default_snippet_visibility" : 0,
+ "restricted_signup_domains" : [],
+ "created_at" : "2016-01-04T15:44:55.176Z",
+ "default_project_visibility" : 0,
+ "gravatar_enabled" : true,
+ "sign_in_text" : null
}
```
-## Change application settings:
-
-
+## Change application settings
```
PUT /application/settings
```
-Parameters:
-
-- `default_projects_limit` - project limit per user
-- `signup_enabled` - enable registration
-- `signin_enabled` - enable login via GitLab account
-- `gravatar_enabled` - enable gravatar
-- `sign_in_text` - text on login page
-- `home_page_url` - redirect to this URL when not logged in
-- `default_branch_protection` - determine if developers can push to master
-- `twitter_sharing_enabled` - allow users to share project creation in twitter
-- `restricted_visibility_levels` - restrict certain visibility levels
-- `max_attachment_size` - limit attachment size
-- `session_expire_delay` - session lifetime
-- `default_project_visibility` - what visibility level new project receives
-- `default_snippet_visibility` - what visibility level new snippet receives
-- `restricted_signup_domains` - force people to use only corporate emails for signup
-- `user_oauth_applications` - allow users to create oauth applications
-- `after_sign_out_path` - where redirect user after logout
+| Attribute | Type | Required | Description |
+| --------- | ---- | :------: | ----------- |
+| `default_projects_limit` | integer | no | Project limit per user. Default is `10` |
+| `signup_enabled` | boolean | no | Enable registration. Default is `true`. |
+| `signin_enabled` | boolean | no | Enable login via a GitLab account. Default is `true`. |
+| `gravatar_enabled` | boolean | no | Enable Gravatar |
+| `sign_in_text` | string | no | Text on login page |
+| `home_page_url` | string | no | Redirect to this URL when not logged in |
+| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `1`. |
+| `twitter_sharing_enabled` | boolean | no | Allow users to share project creation on Twitter |
+| `restricted_visibility_levels` | array of integers | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is null which means there is no restriction. |
+| `max_attachment_size` | integer | no | Limit attachment size in MB |
+| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes |
+| `default_project_visibility` | integer | no | What visibility level new projects receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.|
+| `default_snippet_visibility` | integer | no | What visibility level new snippets receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.|
+| `restricted_signup_domains` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. |
+| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider |
+| `after_sign_out_path` | string | no | Where to redirect users after logout |
-All parameters are optional. You can send only one that you want to change.
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings?signup_enabled=false&default_project_visibility=1
+```
+Example response:
```json
{
@@ -79,7 +89,7 @@ All parameters are optional. You can send only one that you want to change.
"restricted_visibility_levels": [],
"max_attachment_size": 10,
"session_expire_delay": 10080,
- "default_project_visibility": 0,
+ "default_project_visibility": 1,
"default_snippet_visibility": 0,
"restricted_signup_domains": [],
"user_oauth_applications": true,
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index f9637d8a6c4..f539f64488b 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -2,39 +2,58 @@
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 also be configured using the UI in
+[the admin area under hooks](/admin/hooks).
## List system hooks
-Get list of system hooks
+Get a list of all system hooks.
```
GET /hooks
```
-Parameters:
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks
+```
-- **none**
+Example response:
```json
[
- {
- "id": 3,
- "url": "http://example.com/hook",
- "created_at": "2013-10-02T10:15:31Z"
- }
+ {
+ "id" : 1,
+ "url" : "https://gitlab.example.com/hook",
+ "created_at" : "2015-11-04T20:07:35.874Z"
+ }
]
```
-## Add new system hook hook
+## Add new system hook
```
POST /hooks
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `url` | string | yes | The hook URL |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook"
+```
-- `url` (required) - The hook URL
+Example response:
+
+```json
+[
+ {
+ "id" : 2,
+ "url" : "https://gitlab.example.com/hook",
+ "created_at" : "2015-11-04T20:07:35.874Z"
+ }
+]
+```
## Test system hook
@@ -42,29 +61,60 @@ Parameters:
GET /hooks/:id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the hook |
-- `id` (required) - The ID of hook
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
+```
+
+Example response:
```json
{
- "event_name": "project_create",
- "name": "Ruby",
- "path": "ruby",
- "project_id": 1,
- "owner_name": "Someone",
- "owner_email": "example@gitlabhq.com"
+ "project_id" : 1,
+ "owner_email" : "example@gitlabhq.com",
+ "owner_name" : "Someone",
+ "name" : "Ruby",
+ "path" : "ruby",
+ "event_name" : "project_create"
}
```
## 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 a JSON object is
+returned.
```
DELETE /hooks/:id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the hook |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
+```
+
+Example response:
-- `id` (required) - The ID of hook
+```json
+{
+ "note_events" : false,
+ "project_id" : null,
+ "enable_ssl_verification" : true,
+ "url" : "https://gitlab.example.com/hook",
+ "updated_at" : "2015-11-04T20:12:15.931Z",
+ "issues_events" : false,
+ "merge_requests_events" : false,
+ "created_at" : "2015-11-04T20:12:15.931Z",
+ "service_id" : null,
+ "id" : 2,
+ "push_events" : true,
+ "tag_push_events" : false
+}
+```
View Lorry Controller Status