summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md107
-rw-r--r--doc/api/deploy_keys.md87
-rw-r--r--doc/api/groups.md84
-rw-r--r--doc/api/issues.md44
-rw-r--r--doc/api/merge_requests.md20
-rw-r--r--doc/api/milestones.md19
-rw-r--r--doc/api/notes.md115
-rw-r--r--doc/api/project_snippets.md (renamed from doc/api/snippets.md)41
-rw-r--r--doc/api/projects.md341
-rw-r--r--doc/api/repositories.md134
-rw-r--r--doc/api/session.md17
-rw-r--r--doc/api/system_hooks.md49
-rw-r--r--doc/api/user_teams.md209
-rw-r--r--doc/api/users.md118
14 files changed, 1166 insertions, 219 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 0618db7e369..6971e08f010 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,6 +1,6 @@
# GitLab API
-All API requests require authentication. You need to pass a `private_token` parameter by url or header. 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 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.
If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
@@ -18,8 +18,84 @@ Example of a valid API request:
GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U
```
+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.
+
+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
+* `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:
+
+```json
+{
+ "message": "403 Forbidden: Must be admin to use sudo"
+}
+```
+
+If the sudo user id or username cannot be found then an error message will be returned with status code 404:
+
+```json
+{
+ "message": "404 Not Found: No user id or username for: <id/username>"
+}
+```
+
+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"
+```
+
#### Pagination
When listing resources you can pass the following parameters:
@@ -29,12 +105,23 @@ When listing resources you can pass the following parameters:
## Contents
-+ [Users](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/users.md)
-+ [Session](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/session.md)
-+ [Projects](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/projects.md)
-+ [Groups](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/groups.md)
-+ [Snippets](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/snippets.md)
-+ [Repositories](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/repositories.md)
-+ [Issues](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/issues.md)
-+ [Milestones](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/milestones.md)
-+ [Notes](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/notes.md)
++ [Users](users.md)
++ [Session](session.md)
++ [Projects](projects.md)
++ [Project Snippets](project_snippets.md)
++ [Repositories](repositories.md)
++ [Merge Requests](merge_requests.md)
++ [Issues](issues.md)
++ [Milestones](milestones.md)
++ [Notes](notes.md)
++ [Deploy Keys](deploy_keys.md)
++ [System Hooks](system_hooks.md)
++ [Groups](groups.md)
++ [User Teams](user_teams.md)
+
+## Clients
+
++ [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP
++ [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
diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
new file mode 100644
index 00000000000..fbb1e45bccd
--- /dev/null
+++ b/doc/api/deploy_keys.md
@@ -0,0 +1,87 @@
+## Deploy Keys
+
+### List deploy keys
+
+Get a list of a project's deploy keys.
+
+```
+GET /projects/:id/keys
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
+
+```json
+[
+ {
+ "id": 1,
+ "title" : "Public key",
+ "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+ 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+ soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
+ },
+ {
+ "id": 3,
+ "title" : "Another Public key",
+ "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+ 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+ soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+ }
+]
+```
+
+
+### Single deploy key
+
+Get a single key.
+
+```
+GET /projects/:id/keys/:key_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
++ `key_id` (required) - The ID of the deploy key
+
+```json
+{
+ "id": 1,
+ "title" : "Public key",
+ "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+ 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+ soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+}
+```
+
+
+### 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
+
+```
+POST /projects/:id/keys
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
++ `title` (required) - New deploy key's title
++ `key` (required) - New deploy key
+
+
+### Delete deploy key
+
+Delete a deploy key from a project
+
+```
+DELETE /projects/:id/keys/:key_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
++ `key_id` (required) - The ID of the deploy key
+
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 00a7387c76f..9c551fff83a 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -17,7 +17,8 @@ GET /groups
]
```
-## Details of group
+
+## Details of a group
Get all details of a group.
@@ -29,17 +30,90 @@ Parameters:
+ `id` (required) - The ID of a group
+
## New group
-Create a new project group. Available only for admin
+Creates a new project group. Available only for admin.
```
POST /groups
```
Parameters:
-+ `name` (required) - Email
-+ `path` - Password
-Will return created group with status `201 Created` on success, or `404 Not found` on fail.
++ `name` (required) - The name of the group
++ `path` (required) - The path of the group
+
+## 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 of a group
++ `project_id (required) - The ID of a project
+
+
+## Group members
+
+### 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 of a group
++ `user_id` (required) - The ID of a user to add
++ `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 of a user group
++ `user_id` (required) - The ID of a group member
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 0383b676073..723c8acf381 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,6 +1,7 @@
## List issues
-Get all issues created by authenticed user.
+Get all issues created by authenticated user. This function takes pagination parameters
+`page` and `per_page` to restrict the list of issues.
```
GET /issues
@@ -24,7 +25,7 @@ GET /issues
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "closed": true,
+ "state": 'closed',
"updated_at": "2012-07-02T17:53:12Z",
"created_at": "2012-07-02T17:53:12Z"
},
@@ -41,7 +42,7 @@ GET /issues
"title": "v1.0",
"description": "",
"due_date": "2012-07-20",
- "closed": false,
+ "state": 'reopenend',
"updated_at": "2012-07-04T13:42:48Z",
"created_at": "2012-07-04T13:42:48Z"
},
@@ -61,16 +62,18 @@ GET /issues
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "closed": false,
+ "state": 'opened',
"updated_at": "2012-07-12T13:43:19Z",
"created_at": "2012-06-28T12:58:06Z"
}
]
```
+
## List project issues
-Get a list of 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 /projects/:id/issues
@@ -80,9 +83,10 @@ Parameters:
+ `id` (required) - The ID of a project
+
## Single issue
-Get a project issue.
+Gets a single project issue.
```
GET /projects/:id/issues/:issue_id
@@ -107,7 +111,7 @@ Parameters:
"title": "v1.0",
"description": "",
"due_date": "2012-07-20",
- "closed": false,
+ "state": 'closed',
"updated_at": "2012-07-04T13:42:48Z",
"created_at": "2012-07-04T13:42:48Z"
},
@@ -127,15 +131,16 @@ Parameters:
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "closed": false,
+ "state": 'opened',
"updated_at": "2012-07-12T13:43:19Z",
"created_at": "2012-06-28T12:58:06Z"
}
```
+
## New issue
-Create a new project issue.
+Creates a new project issue.
```
POST /projects/:id/issues
@@ -150,11 +155,10 @@ Parameters:
+ `milestone_id` (optional) - The ID of a milestone to assign issue
+ `labels` (optional) - Comma-separated label names for an issue
-Will return created issue with status `201 Created` on success, or `404 Not found` on fail.
## Edit issue
-Update an existing project issue.
+Updates an existing project issue. This function is also used to mark an issue as closed.
```
PUT /projects/:id/issues/:issue_id
@@ -169,7 +173,21 @@ Parameters:
+ `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
-+ `closed` (optional) - The state of an issue (0 = false, 1 = true)
++ `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.
+
+```
+DELETE /projects/:id/issues/:issue_id
+```
+
+Parameters:
-Will return updated issue with status `200 OK` on success, or `404 Not found` on fail.
++ `id` (required) - The project ID
++ `issue_id` (required) - The ID of the issue
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 525c55d12c2..111c52112eb 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -1,6 +1,7 @@
## List merge requests
-Get all MR for this project.
+Get all merge requests for this project. This function takes pagination parameters
+`page` and `per_page` to restrict the list of merge requests.
```
GET /projects/:id/merge_requests
@@ -40,9 +41,10 @@ Parameters:
]
```
-## Show MR
-Show information about MR.
+## Get single MR
+
+Shows information about a single merge request.
```
GET /projects/:id/merge_request/:merge_request_id
@@ -84,7 +86,7 @@ Parameters:
## Create MR
-Create MR.
+Creates a new merge request.
```
POST /projects/:id/merge_requests
@@ -126,9 +128,10 @@ Parameters:
}
```
+
## Update MR
-Update MR. You can change branches, title, or even close the MR.
+Updates an existing merge request. You can change branches, title, or even close the MR.
```
PUT /projects/:id/merge_request/:merge_request_id
@@ -172,9 +175,11 @@ Parameters:
}
}
```
+
+
## Post comment to MR
-Post comment to MR
+Adds a comment to a merge request.
```
POST /projects/:id/merge_request/:merge_request_id/comments
@@ -183,10 +188,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments
Parameters:
+ `id` (required) - The ID of a project
-+ `merge_request_id` (required) - ID of MR
++ `merge_request_id` (required) - ID of merge request
+ `note` (required) - Text of comment
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
```json
{
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index b997e83901b..aa8f1bf5e02 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -1,6 +1,6 @@
## List project milestones
-Get a list of project milestones.
+Returns a list of project milestones.
```
GET /projects/:id/milestones
@@ -10,9 +10,10 @@ Parameters:
+ `id` (required) - The ID of a project
-## Single milestone
-Get a single project milestone.
+## Get single milestone
+
+Gets a single project milestone.
```
GET /projects/:id/milestones/:milestone_id
@@ -23,9 +24,10 @@ Parameters:
+ `id` (required) - The ID of a project
+ `milestone_id` (required) - The ID of a project milestone
-## New milestone
-Create a new project milestone.
+## Create new milestone
+
+Creates a new project milestone.
```
POST /projects/:id/milestones
@@ -34,14 +36,14 @@ POST /projects/:id/milestones
Parameters:
+ `id` (required) - The ID of a project
-+ `milestone_id` (required) - The ID of a project milestone
+ `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
-Update an existing project milestone.
+Updates an existing project milestone.
```
PUT /projects/:id/milestones/:milestone_id
@@ -54,4 +56,5 @@ Parameters:
+ `title` (optional) - The title of a milestone
+ `description` (optional) - The description of a milestone
+ `due_date` (optional) - The due date of the milestone
-+ `closed` (optional) - The status of the milestone
++ `state_event` (optional) - The state event of the milestone (close|activate)
+
diff --git a/doc/api/notes.md b/doc/api/notes.md
index a4ba2826076..4b57f636a01 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -1,4 +1,4 @@
-## List notes
+## Wall
### List project wall notes
@@ -30,22 +30,40 @@ Parameters:
+ `id` (required) - The ID of a project
-### List merge request notes
-Get a list of merge request notes.
+### Get single wall note
+
+Returns a single wall note.
```
-GET /projects/:id/merge_requests/:merge_request_id/notes
+GET /projects/:id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
-+ `merge_request_id` (required) - The ID of an merge request
++ `note_id` (required) - The ID of a wall note
-### List issue notes
-Get a list of issue notes.
+### Create new wall note
+
+Creates a new wall note.
+
+```
+POST /projects/:id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `body` (required) - The content of a note
+
+
+## Issues
+
+### List project issue notes
+
+Gets a list of all notes for a single issue.
```
GET /projects/:id/issues/:issue_id/notes
@@ -56,54 +74,59 @@ Parameters:
+ `id` (required) - The ID of a project
+ `issue_id` (required) - The ID of an issue
-### List snippet notes
-Get a list of snippet notes.
+### Get single issue note
+
+Returns a single note for a specific project issue
```
-GET /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/issues/:issue_id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a snippet
++ `issue_id` (required) - The ID of a project issue
++ `note_id` (required) - The ID of an issue note
-## Single note
-### Single wall note
+### Create new issue note
-Get a wall note.
+Creates a new note to a single project issue.
```
-GET /projects/:id/notes/:note_id
+POST /projects/:id/issues/:issue_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
-+ `note_id` (required) - The ID of a wall note
++ `issue_id` (required) - The ID of an issue
++ `body` (required) - The content of a note
-### Single issue note
-Get an issue note.
+## Snippets
+
+### List all snippet notes
+
+Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
```
-GET /projects/:id/issues/:issue_id/:notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of a project issue
-+ `note_id` (required) - The ID of an issue note
++ `snippet_id` (required) - The ID of a project snippet
+
-### Single snippet note
+### Get single snippet note
-Get a snippet note.
+Returns a single note for a given snippet.
```
-GET /projects/:id/issues/:snippet_id/:notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
@@ -112,52 +135,64 @@ Parameters:
+ `snippet_id` (required) - The ID of a project snippet
+ `note_id` (required) - The ID of an snippet note
-## New note
-### New wall note
+### Create new snippet note
-Create a new wall note.
+Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
```
-POST /projects/:id/notes
+POST /projects/:id/snippets/:snippet_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
++ `snippet_id` (required) - The ID of an snippet
+ `body` (required) - The content of a note
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
+## Merge Requests
-### New issue note
+### List all merge request notes
-Create a new issue note.
+Gets a list of all notes for a single merge request.
```
-POST /projects/:id/issues/:issue_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of an issue
-+ `body` (required) - The content of a note
++ `merge_request_id` (required) - The ID of a project merge request
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
-### New snippet note
+### Get single merge request note
-Create a new snippet note.
+Returns a single note for a given merge request.
```
-POST /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of an snippet
++ `merge_request_id` (required) - The ID of a project merge request
++ `note_id` (required) - The ID of a merge request note
+
+
+### Create new merge request note
+
+Creates a new note for a single merge request.
+
+```
+POST /projects/:id/merge_requests/:merge_request_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `merge_request_id` (required) - The ID of a merge request
+ `body` (required) - The content of a note
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
diff --git a/doc/api/snippets.md b/doc/api/project_snippets.md
index ceb8a63d06f..04ea367d518 100644
--- a/doc/api/snippets.md
+++ b/doc/api/project_snippets.md
@@ -10,9 +10,10 @@ Parameters:
+ `id` (required) - The ID of a project
+
## Single snippet
-Get a project snippet.
+Get a single project snippet.
```
GET /projects/:id/snippets/:snippet_id
@@ -42,22 +43,10 @@ Parameters:
}
```
-## Snippet content
-
-Get a raw project snippet.
-
-```
-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
-## New snippet
+## Create new snippet
-Create a new project snippet.
+Creates a new project snippet. The user must have permission to create new snippets.
```
POST /projects/:id/snippets
@@ -71,11 +60,10 @@ Parameters:
+ `lifetime` (optional) - The expiration date of a snippet
+ `code` (required) - The content of a snippet
-Will return created snippet with status `201 Created` on success, or `404 Not found` on fail.
-## Edit snippet
+## Update snippet
-Update an existing project snippet.
+Updates an existing project snippet. The user must have permission to change an existing snippet.
```
PUT /projects/:id/snippets/:snippet_id
@@ -90,11 +78,11 @@ Parameters:
+ `lifetime` (optional) - The expiration date of a snippet
+ `code` (optional) - The content of a snippet
-Will return updated snippet with status `200 OK` on success, or `404 Not found` on fail.
## Delete snippet
-Delete existing project snippet.
+Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
+snippet still returns a `200 Ok` status code.
```
DELETE /projects/:id/snippets/:snippet_id
@@ -105,5 +93,16 @@ Parameters:
+ `id` (required) - The ID of a project
+ `snippet_id` (required) - The ID of a project's snippet
-Status code `200` will be returned on success.
+## Snippet content
+
+Returns the raw project snippet as plain text.
+
+```
+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
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 82bb0c0d561..5150331e7d7 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,4 +1,6 @@
-## List projects
+## Projects
+
+### List projects
Get a list of projects owned by the authenticated user.
@@ -21,14 +23,15 @@ GET /projects
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "private": true,
+ "public": true,
"path": "rails",
"path_with_namespace": "rails/rails",
"issues_enabled": false,
"merge_requests_enabled": false,
"wall_enabled": true,
"wiki_enabled": true,
- "created_at": "2012-05-23T08:05:02Z"
+ "created_at": "2012-05-23T08:05:02Z",
+ "last_activity_at": "2012-05-23T08:05:02Z"
},
{
"id": 5,
@@ -43,21 +46,25 @@ GET /projects
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "private": true,
+ "public": true,
"path": "gitlab",
"path_with_namespace": "randx/gitlab",
"issues_enabled": true,
"merge_requests_enabled": true,
"wall_enabled": true,
"wiki_enabled": true,
- "created_at": "2012-05-30T12:49:20Z"
+ "snippets_enabled": true,
+ "created_at": "2012-05-30T12:49:20Z",
+ "last_activity_at": "2012-05-23T08:05:02Z"
}
]
```
-## Single project
-Get a specific project, identified by project ID, which is owned by the authentication user.
+### Get single project
+
+Get a specific project, identified by project ID or NAME, which is owned by the authentication user.
+Currently namespaced projects cannot retrieved by name.
```
GET /projects/:id
@@ -65,12 +72,13 @@ GET /projects/:id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
```json
{
"id": 5,
"name": "gitlab",
+ "name_with_namespace": "GitLab / gitlabhq",
"description": null,
"default_branch": "api",
"owner": {
@@ -81,20 +89,91 @@ Parameters:
"blocked": false,
"created_at": "2012-05-23T08:00:58Z"
},
- "private": true,
+ "public": true,
"path": "gitlab",
"path_with_namespace": "randx/gitlab",
"issues_enabled": true,
"merge_requests_enabled": true,
"wall_enabled": true,
"wiki_enabled": true,
- "created_at": "2012-05-30T12:49:20Z"
+ "snippets_enabled": true,
+ "created_at": "2012-05-30T12:49:20Z",
+ "last_activity_at": "2012-05-23T08:05:02Z"
}
```
-## Create project
+### Get project events
+
+Get a project events for specific project.
+Sorted from newest to latest
+
+```
+GET /projects/:id/events
+```
+
+Parameters:
+
++ `id` (required) - The ID or NAME of a project
+
+```json
+
+[{
+ "title": null,
+ "project_id": 15,
+ "action_name": "closed",
+ "target_id": 830,
+ "target_type": "Issue",
+ "author_id": 1,
+ "data": null,
+ "target_title": "Public project search field"
+}, {
+ "title": null,
+ "project_id": 15,
+ "action_name": "opened",
+ "target_id": null,
+ "target_type": null,
+ "author_id": 1,
+ "data": {
+ "before": "50d4420237a9de7be1304607147aec22e4a14af7",
+ "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
+ "ref": "refs/heads/master",
+ "user_id": 1,
+ "user_name": "Dmitriy Zaporozhets",
+ "repository": {
+ "name": "gitlabhq",
+ "url": "git@dev.gitlab.org:gitlab/gitlabhq.git",
+ "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.",
+ "homepage": "https://dev.gitlab.org/gitlab/gitlabhq"
+ },
+ "commits": [{
+ "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
+ "message": "Add simple search to projects in public area",
+ "timestamp": "2013-05-13T18:18:08+00:00",
+ "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428",
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "email": "dmitriy.zaporozhets@gmail.com"
+ }
+ }],
+ "total_commits_count": 1
+ },
+ "target_title": null
+}, {
+ "title": null,
+ "project_id": 15,
+ "action_name": "closed",
+ "target_id": 840,
+ "target_type": "Issue",
+ "author_id": 1,
+ "data": null,
+ "target_title": "Finish & merge Code search PR"
+}]
+```
+
-Create new project owned by user
+### Create project
+
+Creates new project owned by user.
```
POST /projects
@@ -105,15 +184,51 @@ Parameters:
+ `name` (required) - new project name
+ `description` (optional) - short project description
+ `default_branch` (optional) - 'master' by default
-+ `issues_enabled` (optional) - enabled by default
-+ `wall_enabled` (optional) - enabled by default
-+ `merge_requests_enabled` (optional) - enabled by default
-+ `wiki_enabled` (optional) - enabled by default
++ `issues_enabled` (optional)
++ `wall_enabled` (optional)
++ `merge_requests_enabled` (optional)
++ `wiki_enabled` (optional)
++ `snippets_enabled` (optional)
++ `public` (optional)
+
+**Project access levels**
+
+The project access levels are defined in the `user_project.rb` class. Currently, these levels are recognized:
+
+```
+ GUEST = 10
+ REPORTER = 20
+ DEVELOPER = 30
+ MASTER = 40
+```
+
-Will return created project with status `201 Created` on success, or `404 Not
-found` on fail.
+### Create project for user
-## List project team members
+Creates a new project owned by user. Available only for admins.
+
+```
+POST /projects/user/:user_id
+```
+
+Parameters:
+
++ `user_id` (required) - user_id of owner
++ `name` (required) - new project name
++ `description` (optional) - short project description
++ `default_branch` (optional) - 'master' by default
++ `issues_enabled` (optional)
++ `wall_enabled` (optional)
++ `merge_requests_enabled` (optional)
++ `wiki_enabled` (optional)
++ `snippets_enabled` (optional)
++ `public` (optional)
+
+
+
+## Team members
+
+### List project team members
Get a list of project team members.
@@ -123,12 +238,13 @@ GET /projects/:id/members
Parameters:
-+ `id` (required) - The ID of a project
-+ `query` - Query string
++ `id` (required) - The ID or NAME of a project
++ `query` (optional) - Query string to search for members
+
-## Get project team member
+### Get project team member
-Get a project team member.
+Gets a project team member.
```
GET /projects/:id/members/:user_id
@@ -136,12 +252,11 @@ GET /projects/:id/members/:user_id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `user_id` (required) - The ID of a user
```json
{
-
"id": 1,
"username": "john_smith",
"email": "john@example.com",
@@ -152,9 +267,12 @@ Parameters:
}
```
-## Add project team member
-Add a user to a project team.
+### Add project team member
+
+Adds a user to a project team. This is an idempotent method and can be called multiple times
+with the same parameters. Adding team membership to a user that is already a member does not
+affect the existing membership.
```
POST /projects/:id/members
@@ -162,15 +280,14 @@ POST /projects/:id/members
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `user_id` (required) - The ID of a user to add
+ `access_level` (required) - Project access level
-Will return status `201 Created` on success, or `404 Not found` on fail.
-## Edit project team member
+### Edit project team member
-Update project team member to specified access level.
+Updates project team member to a specified access level.
```
PUT /projects/:id/members/:user_id
@@ -178,13 +295,12 @@ PUT /projects/:id/members/:user_id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `user_id` (required) - The ID of a team member
+ `access_level` (required) - Project access level
-Will return status `200 OK` on success, or `404 Not found` on fail.
-## Remove project team member
+### Remove project team member
Removes user from project team.
@@ -194,14 +310,20 @@ DELETE /projects/:id/members/:user_id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `user_id` (required) - The ID of a team member
-Status code `200` will be returned on success.
+This method is idempotent and can be called multiple times with the same parameters.
+Revoking team membership for a user who is not currently a team member is considered success.
+Please note that the returned JSON currently differs slightly. Thus you should not
+rely on the returned JSON structure.
-## List project hooks
-Get list for project hooks
+## Hooks
+
+### List project hooks
+
+Get list of project hooks.
```
GET /projects/:id/hooks
@@ -209,13 +331,12 @@ GET /projects/:id/hooks
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
-Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
-## Get project hook
+### Get project hook
-Get hook for project
+Get a specific hook for project.
```
GET /projects/:id/hooks/:hook_id
@@ -223,14 +344,21 @@ GET /projects/:id/hooks/:hook_id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `hook_id` (required) - The ID of a project hook
-Will return hook with status `200 OK` on success, or `404 Not found` on fail.
+```json
+{
+ "id": 1,
+ "url": "http://example.com/hook",
+ "created_at": "2012-10-12T17:04:47Z"
+}
+```
-## Add project hook
-Add hook to project
+### Add project hook
+
+Adds a hook to project.
```
POST /projects/:id/hooks
@@ -238,14 +366,13 @@ POST /projects/:id/hooks
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `url` (required) - The hook URL
-Will return status `201 Created` on success, or `404 Not found` on fail.
-## Edit project hook
+### Edit project hook
-Edit hook for project
+Edits a hook for project.
```
PUT /projects/:id/hooks/:hook_id
@@ -253,24 +380,122 @@ PUT /projects/:id/hooks/:hook_id
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `hook_id` (required) - The ID of a project hook
+ `url` (required) - The hook URL
-Will return status `201 Created` on success, or `404 Not found` on fail.
-
-## Delete project hook
+### Delete project hook
-Delete hook from project
+Removes a hook from project. This is an idempotent method and can be called multiple times.
+Either the hook is available or not.
```
-DELETE /projects/:id/hooks
+DELETE /projects/:id/hooks/:hook_id
```
Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
+ `hook_id` (required) - The ID of hook to delete
-Will return status `200 OK` on success, or `404 Not found` on fail.
+Note the JSON response differs if the hook is available or not. If the project hook
+is available before it is returned in the JSON response or an empty response is returned.
+
+
+## Branches
+
+### List branches
+
+Lists all branches of a project.
+
+```
+GET /projects/:id/repository/branches
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
+
+
+### List single branch
+
+Lists a specific branch of a project.
+
+```
+GET /projects/:id/repository/branches/:branch
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+### Protect single branch
+
+Protects a single branch of a project.
+
+```
+PUT /projects/:id/repository/branches/:branch/protect
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+### Unprotect single branch
+
+Unprotects a single branch of a project.
+
+```
+PUT /projects/:id/repository/branches/:branch/unprotect
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+## Admin fork relation
+
+Allows modification of the forked relationship between existing projects. . Available only for admins.
+
+### Create a forked from/to relation between existing projects.
+
+```
+POST /projects/:id/fork/:forked_from_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
++ `forked_from_id:` (required) - The ID of the project that was forked from
+
+### Delete an existing forked from relationship
+
+```
+DELETE /projects/:id/fork
+```
+
+Parameter:
+
++ `id` (required) - The ID of the project
+
+
+## Search for projects by name
+
+Search for projects by name which are public or the calling user has access to
+
+```
+GET /projects/search/:query
+```
+
+Parameters:
+
++ query (required) - A string contained in the project name
++ per_page (optional) - number of projects to return per page
++ page (optional) - the page to retrieve
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index fd0ef1f53eb..cb0626972e5 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -1,4 +1,4 @@
-## Project repository branches
+## List repository branches
Get a list of repository branches from a project, sorted by name alphabetically.
@@ -39,7 +39,8 @@ Parameters:
]
```
-## Project repository branch
+
+## Get single repository branch
Get a single project repository branch.
@@ -79,12 +80,11 @@ Parameters:
}
```
-Will return status code `200` on success or `404 Not found` if the branch is not available.
-
-## Protect a project repository branch
+## Protect repository branch
-Protect a single project 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.
```
PUT /projects/:id/repository/branches/:branch/protect
@@ -122,9 +122,11 @@ Parameters:
}
```
-## Unprotect a project repository branch
-Unprotect a single project repository branch.
+## 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.
```
PUT /projects/:id/repository/branches/:branch/unprotect
@@ -162,7 +164,8 @@ Parameters:
}
```
-## Project repository tags
+
+## List project repository tags
Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
@@ -201,7 +204,8 @@ Parameters:
]
```
-## Project repository commits
+
+## List repository commits
Get a list of repository commits in a project.
@@ -212,7 +216,7 @@ GET /projects/:id/repository/commits
Parameters:
+ `id` (required) - The ID of a project
-+ `ref_name` (optional) - The name of a repository branch or tag
++ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
```json
[
@@ -235,12 +239,116 @@ Parameters:
]
```
+## Get a single commit
+
+Get a specific commit identified by the commit hash or name of a branch or tag.
+
+```
+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
+
+```json
+{
+ "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
+ "short_id": "6104942438c",
+ "title": "Sanitize for network graph",
+ "author_name": "randx",
+ "author_email": "dmitriy.zaporozhets@gmail.com",
+ "created_at": "2012-09-20T09:06:12+03:00"
+}
+```
+
+
+## Get the diff of a commit
+
+Get the diff of a commit in a project.
+
+```
+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
+
+```json
+[
+ {
+ "diff": "--- a/doc/update/5.4-to-6.0.md\n+++ b/doc/update/5.4-to-6.0.md\n@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files",
+ "new_path": "doc/update/5.4-to-6.0.md",
+ "old_path": "doc/update/5.4-to-6.0.md",
+ "a_mode": null,
+ "b_mode": "100644",
+ "new_file": false,
+ "renamed_file": false,
+ "deleted_file": false
+ }
+]
+```
+
+## List repository tree
+
+Get a list of repository files and directories in a project.
+
+```
+GET /projects/:id/repository/tree
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `path` (optional) - The path inside repository. Used to get contend of subdirectories
++ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
+
+```json
+
+[{
+ "name": "assets",
+ "type": "tree",
+ "mode": "040000",
+ "id": "6229c43a7e16fcc7e95f923f8ddadb8281d9c6c6"
+}, {
+ "name": "contexts",
+ "type": "tree",
+ "mode": "040000",
+ "id": "faf1cdf33feadc7973118ca42d35f1e62977e91f"
+}, {
+ "name": "controllers",
+ "type": "tree",
+ "mode": "040000",
+ "id": "95633e8d258bf3dfba3a5268fb8440d263218d74"
+}, {
+ "name": "Rakefile",
+ "type": "blob",
+ "mode": "100644",
+ "id": "35b2f05cbb4566b71b34554cf184a9d0bd9d46d6"
+}, {
+ "name": "VERSION",
+ "type": "blob",
+ "mode": "100644",
+ "id": "803e4a4f3727286c3093c63870c2b6524d30ec4f"
+}, {
+ "name": "config.ru",
+ "type": "blob",
+ "mode": "100644",
+ "id": "dfd2d862237323aa599be31b473d70a8a817943b"
+}]
+
+```
+
+
## Raw blob content
Get the raw file contents for a file.
```
-GET /projects/:id/repository/commits/:sha/blob
+GET /projects/:id/repository/blobs/:sha
```
Parameters:
@@ -248,5 +356,3 @@ Parameters:
+ `id` (required) - The ID of a project
+ `sha` (required) - The commit or branch name
+ `filepath` (required) - The path the file
-
-Will return the raw file contents.
diff --git a/doc/api/session.md b/doc/api/session.md
index c7e57aaca7a..162d4c8bf78 100644
--- a/doc/api/session.md
+++ b/doc/api/session.md
@@ -6,10 +6,13 @@ POST /session
Parameters:
-+ `email` (required) - The email of 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__
+
```json
{
"id": 1,
@@ -17,7 +20,17 @@ Parameters:
"email": "john@example.com",
"name": "John Smith",
"private_token": "dd34asd13as",
+ "blocked": false,
"created_at": "2012-05-23T08:00:58Z",
- "blocked": true
+ "bio": null,
+ "skype": "",
+ "linkedin": "",
+ "twitter": "",
+ "dark_scheme": false,
+ "theme_id": 1,
+ "is_admin": false,
+ "can_create_group" : true,
+ "can_create_team" : true,
+ "can_create_project" : true
}
```
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
new file mode 100644
index 00000000000..dca22c43f83
--- /dev/null
+++ b/doc/api/system_hooks.md
@@ -0,0 +1,49 @@
+All methods require admin authorization.
+
+## List system hooks
+
+Get list of system hooks
+
+```
+GET /hooks
+```
+
+Parameters:
+
++ **none**
+
+
+## Add new system hook hook
+
+```
+POST /hooks
+```
+
+Parameters:
+
++ `url` (required) - The hook URL
+
+
+## Test system hook
+
+```
+GET /hooks/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of hook
+
+
+## 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.
+
+```
+DELETE /hooks/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of hook
diff --git a/doc/api/user_teams.md b/doc/api/user_teams.md
new file mode 100644
index 00000000000..cf467a54667
--- /dev/null
+++ b/doc/api/user_teams.md
@@ -0,0 +1,209 @@
+## User teams
+
+### List user teams
+
+Get a list of user teams viewable by the authenticated user.
+
+```
+GET /user_teams
+```
+
+```json
+[
+ {
+ id: 1,
+ name: "User team 1",
+ path: "user_team1",
+ owner_id: 1
+ },
+ {
+ id: 2,
+ name: "User team 2",
+ path: "user_team2",
+ owner_id: 1
+ }
+]
+```
+
+
+### Get single user team
+
+Get a specific user team, identified by user team ID, which is viewable by the authenticated user.
+
+```
+GET /user_teams/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user_team
+
+```json
+{
+ id: 1,
+ name: "User team 1",
+ path: "user_team1",
+ owner_id: 1
+}
+```
+
+
+### Create user team
+
+Creates new user team owned by user. Available only for admins.
+
+```
+POST /user_teams
+```
+
+Parameters:
+
++ `name` (required) - new user team name
++ `path` (required) - new user team internal name
+
+
+
+## User team members
+
+### List user team members
+
+Get a list of project team members.
+
+```
+GET /user_teams/:id/members
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user_team
+
+
+### Get user team member
+
+Gets a user team member.
+
+```
+GET /user_teams/:id/members/:user_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user_team
++ `user_id` (required) - The ID of a user
+
+```json
+{
+ 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 user team member
+
+Adds a user to a user team.
+
+```
+POST /user_teams/:id/members
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user team
++ `user_id` (required) - The ID of a user to add
++ `access_level` (required) - Project access level
+
+
+### Remove user team member
+
+Removes user from user team.
+
+```
+DELETE /user_teams/:id/members/:user_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user team
++ `user_id` (required) - The ID of a team member
+
+## User team projects
+
+### List user team projects
+
+Get a list of project team projects.
+
+```
+GET /user_teams/:id/projects
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user_team
+
+
+### Get user team project
+
+Gets a user team project.
+
+```
+GET /user_teams/:id/projects/:project_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user_team
++ `project_id` (required) - The ID of a user
+
+```json
+{
+ id: 12,
+ name: "project1",
+ description: null,
+ default_branch: "develop",
+ public: false,
+ path: "project1",
+ path_with_namespace: "group1/project1",
+ issues_enabled: false,
+ merge_requests_enabled: true,
+ wall_enabled: true,
+ wiki_enabled: false,
+ created_at: "2013-03-11T12:59:08Z",
+ greatest_access_level: 30
+}
+```
+
+
+### Add user team project
+
+Adds a project to a user team.
+
+```
+POST /user_teams/:id/projects
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user team
++ `project_id` (required) - The ID of a project to add
++ `greatest_access_level` (required) - Maximum project access level
+
+
+### Remove user team project
+
+Removes project from user team.
+
+```
+DELETE /user_teams/:id/projects/:project_id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a user team
++ `project_id` (required) - The ID of a team project
+
diff --git a/doc/api/users.md b/doc/api/users.md
index b94d7c0f789..49afbab8c6a 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -1,6 +1,7 @@
## List users
Get a list of users.
+This function takes pagination parameters `page` and `per_page` to restrict the list of users.
```
GET /users
@@ -13,36 +14,37 @@ GET /users
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
- "blocked": false,
+ "state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
- "dark_scheme": false,
"extern_uid": "john.smith",
"provider": "provider_name",
- "theme_id": 1
+ "theme_id": 1,
+ "color_scheme_id": 2
},
{
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
- "blocked": false,
+ "state": "blocked",
"created_at": "2012-05-23T08:01:01Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
- "dark_scheme": true,
"extern_uid": "jack.smith",
"provider": "provider_name",
- "theme_id": 1
+ "theme_id": 1,
+ "color_scheme_id": 3
}
]
```
+
## Single user
Get a single user.
@@ -61,50 +63,53 @@ Parameters:
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
- "blocked": false,
+ "state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
- "dark_scheme": false,
"extern_uid": "john.smith",
"provider": "provider_name",
- "theme_id": 1
+ "theme_id": 1,
+ "color_scheme_id": 2
}
```
+
## User creation
-Create user. Available only for admin
+
+Creates a new user. Note only administrators can create new users.
```
POST /users
```
Parameters:
-+ `email` (required) - Email
-+ `password` (required) - Password
-+ `username` (required) - Username
-+ `name` (required) - Name
-+ `skype` - Skype ID
-+ `linkedin` - Linkedin
-+ `twitter` - Twitter account
-+ `projects_limit` - Number of projects user can create
-+ `extern_uid` - External UID
-+ `provider` - External provider name
-+ `bio` - User's bio
-Will return created user with status `201 Created` on success, or `404 Not
-found` on fail.
++ `email` (required) - Email
++ `password` (required) - Password
++ `username` (required) - Username
++ `name` (required) - Name
++ `skype` (optional) - Skype ID
++ `linkedin` (optional) - Linkedin
++ `twitter` (optional) - Twitter account
++ `projects_limit` (optional) - Number of projects user can create
++ `extern_uid` (optional) - External UID
++ `provider` (optional) - External provider name
++ `bio` (optional) - User's bio
+
## User modification
-Modify user. Available only for admin
+
+Modifies an existing user. Only administrators can change attributes of a user.
```
PUT /users/:id
```
Parameters:
+
+ `email` - Email
+ `username` - Username
+ `name` - Name
@@ -112,28 +117,33 @@ Parameters:
+ `skype` - Skype ID
+ `linkedin` - Linkedin
+ `twitter` - Twitter account
-+ `projects_limit` - Limit projects wich user can create
++ `projects_limit` - Limit projects each user can create
+ `extern_uid` - External UID
+ `provider` - External provider name
+ `bio` - User's bio
+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.
-Will return created user with status `200 OK` on success, or `404 Not
-found` on fail.
## User deletion
-Delete user. Available only for admin
+
+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
```
-Will return deleted user with status `200 OK` on success, or `404 Not
-found` on fail.
+Parameters:
+
++ `id` (required) - The ID of the user
+
## Current user
-Get currently authenticated user.
+Gets currently authenticated user.
```
GET /user
@@ -145,17 +155,23 @@ GET /user
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
- "blocked": false,
+ "private_token": "dd34asd13as",
+ "state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
- "dark_scheme": false,
- "theme_id": 1
+ "theme_id": 1,
+ "color_scheme_id": 2,
+ "is_admin": false,
+ "can_create_group" : true,
+ "can_create_team" : true,
+ "can_create_project" : true
}
```
+
## List SSH keys
Get a list of currently authenticated user's SSH keys.
@@ -168,14 +184,14 @@ GET /user/keys
[
{
"id": 1,
- "title" : "Public key"
+ "title" : "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
},
{
"id": 3,
- "title" : "Another Public key"
+ "title" : "Another Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
@@ -183,6 +199,11 @@ GET /user/keys
]
```
+Parameters:
+
++ **none**
+
+
## Single SSH key
Get a single key.
@@ -198,15 +219,17 @@ Parameters:
```json
{
"id": 1,
- "title" : "Public key"
+ "title" : "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
}
```
+
+
## Add SSH key
-Create new key owned by currently authenticated user
+Creates a new key owned by the currently authenticated user.
```
POST /user/keys
@@ -217,12 +240,28 @@ Parameters:
+ `title` (required) - new SSH Key's title
+ `key` (required) - new SSH key
+
+## Add SSH key for user
+
+Create new key owned by specified user. Available only for admin
+
+```
+POST /users/:id/keys
+```
+
+Parameters:
+
++ `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.
## Delete SSH key
-Delete key owned by currently authenticated 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`.
```
DELETE /user/keys/:id
@@ -232,4 +271,3 @@ Parameters:
+ `id` (required) - SSH key ID
-Will return `200 OK` on success, or `404 Not Found` on fail.
View Lorry Controller Status