Merge branch 'master' into mmonaco/gitlab-ce-api-user-noconfirm

Conflicts:
	lib/api/users.rb

12 files changed, 532 insertions, 111 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index ffe250df3ff..dec530d0b81 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -22,6 +22,7 @@
 ## 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
 
@@ -51,6 +52,24 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p
 
 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.
+
+### OAuth2 token (as a parameter)
+
+```
+curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
+```
+
+###  OAuth2 token (as a header)
+
+```
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/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.
@@ -79,7 +98,7 @@ Return values:
 
 ## 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, 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:
 
@@ -124,7 +143,7 @@ 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
 
-[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own urls.
+[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own URLs.
 
 ## id vs iid
 
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 319f0b47386..6a9c10c8520 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -15,27 +15,20 @@ Parameters:
 ```json
 [
   {
-    "name": "master",
     "commit": {
+      "author_email": "john@example.com",
+      "author_name": "John Smith",
+      "authored_date": "2012-06-27T05:51:39-07:00",
+      "committed_date": "2012-06-28T03:44:20-07:00",
+      "committer_email": "john@example.com",
+      "committer_name": "John Smith",
       "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
-      "parents": [
-        {
-          "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
-        }
-      ],
-      "tree": "46e82de44b1061621357f24c05515327f2795a95",
       "message": "add projects API",
-      "author": {
-        "name": "John Smith",
-        "email": "john@example.com"
-      },
-      "committer": {
-        "name": "John Smith",
-        "email": "john@example.com"
-      },
-      "authored_date": "2012-06-27T05:51:39-07:00",
-      "committed_date": "2012-06-28T03:44:20-07:00"
+      "parent_ids": [
+        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+      ]
     },
+    "name": "master",
     "protected": true
   }
 ]
@@ -56,27 +49,20 @@ Parameters:
 
 ```json
 {
-  "name": "master",
   "commit": {
+    "author_email": "john@example.com",
+    "author_name": "John Smith",
+    "authored_date": "2012-06-27T05:51:39-07:00",
+    "committed_date": "2012-06-28T03:44:20-07:00",
+    "committer_email": "john@example.com",
+    "committer_name": "John Smith",
     "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
-    "parents": [
-      {
-        "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
-      }
-    ],
-    "tree": "46e82de44b1061621357f24c05515327f2795a95",
     "message": "add projects API",
-    "author": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "committer": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "authored_date": "2012-06-27T05:51:39-07:00",
-    "committed_date": "2012-06-28T03:44:20-07:00"
+    "parent_ids": [
+      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+    ]
   },
+  "name": "master",
   "protected": true
 }
 ```
@@ -97,27 +83,20 @@ Parameters:
 
 ```json
 {
-  "name": "master",
   "commit": {
+    "author_email": "john@example.com",
+    "author_name": "John Smith",
+    "authored_date": "2012-06-27T05:51:39-07:00",
+    "committed_date": "2012-06-28T03:44:20-07:00",
+    "committer_email": "john@example.com",
+    "committer_name": "John Smith",
     "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
-    "parents": [
-      {
-        "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
-      }
-    ],
-    "tree": "46e82de44b1061621357f24c05515327f2795a95",
     "message": "add projects API",
-    "author": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "committer": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "authored_date": "2012-06-27T05:51:39-07:00",
-    "committed_date": "2012-06-28T03:44:20-07:00"
+    "parent_ids": [
+      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+    ]
   },
+  "name": "master",
   "protected": true
 }
 ```
@@ -138,27 +117,20 @@ Parameters:
 
 ```json
 {
-  "name": "master",
   "commit": {
+    "author_email": "john@example.com",
+    "author_name": "John Smith",
+    "authored_date": "2012-06-27T05:51:39-07:00",
+    "committed_date": "2012-06-28T03:44:20-07:00",
+    "committer_email": "john@example.com",
+    "committer_name": "John Smith",
     "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
-    "parents": [
-      {
-        "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
-      }
-    ],
-    "tree": "46e82de44b1061621357f24c05515327f2795a95",
     "message": "add projects API",
-    "author": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "committer": {
-      "name": "John Smith",
-      "email": "john@example.com"
-    },
-    "authored_date": "2012-06-27T05:51:39-07:00",
-    "committed_date": "2012-06-28T03:44:20-07:00"
+    "parent_ids": [
+      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+    ]
   },
+  "name": "master",
   "protected": false
 }
 ```
@@ -177,21 +149,20 @@ Parameters:
 
 ```json
 {
-  "name": "my-new-branch",
   "commit": {
-    "id": "8848c0e90327a0b70f1865b843fb2fbfb9345e57",
-    "message": "Merge pull request #54 from brightbox/use_fog_brightbox_module\n\nUpdate to use fog-brightbox module",
-    "parent_ids": [
-      "fff449e0bf453576f16c91d6544f00a2664009d8",
-      "f93a93626fec20fd659f4ed3ab2e64019b6169ae"
-    ],
-    "authored_date": "2014-02-20T19:54:55+02:00",
-    "author_name": "john smith",
     "author_email": "john@example.com",
-    "committed_date": "2014-02-20T19:54:55+02:00",
-    "committer_name": "john smith",
-    "committer_email": "john@example.com"
+    "author_name": "John Smith",
+    "authored_date": "2012-06-27T05:51:39-07:00",
+    "committed_date": "2012-06-28T03:44:20-07:00",
+    "committer_email": "john@example.com",
+    "committer_name": "John Smith",
+    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
+    "message": "add projects API",
+    "parent_ids": [
+      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+    ]
   },
+  "name": "master",
   "protected": false
 }
 ```
diff --git a/doc/api/commits.md b/doc/api/commits.md
index 9475ecbaa67..eb8d6a43592 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -93,3 +93,66 @@ Parameters:
   }
 ]
 ```
+
+## Get the comments of a commit
+
+Get the comments of a commit in a project.
+
+```
+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
+
+```json
+[
+  {
+    "note": "this code is really nice",
+    "author": {
+      "id": 11,
+      "username": "admin",
+      "email": "admin@local.host",
+      "name": "Administrator",
+      "state": "active",
+      "created_at": "2014-03-06T08:17:35.000Z"
+    }
+  }
+]
+```
+
+## 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.
+
+```
+POST /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
+- `note` (required)             - Text of comment
+- `path` (optional)             - The file path
+- `line` (optional)             - The line number
+- `line_type` (optional)        - The line type (new or old)
+
+```json
+{
+  "author": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@local.host",
+    "name": "Administrator",
+    "blocked": false,
+    "created_at": "2012-04-29T08:46:00Z"
+  },
+  "note": "text1",
+  "path": "example.rb",
+  "line": 5,
+  "line_type": "new"
+}
+```
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 6b379b02d28..b5a4b05ccaf 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -14,11 +14,13 @@ GET /groups
     "id": 1,
     "name": "Foobar Group",
     "path": "foo-bar",
-    "owner_id": 18
+    "description": "An interesting group"
   }
 ]
 ```
 
+You can search for groups by name or path, see below.
+
 ## Details of a group
 
 Get all details of a group.
@@ -29,7 +31,7 @@ GET /groups/:id
 
 Parameters:
 
-- `id` (required) - The ID of a group
+- `id` (required) - The ID or path of a group
 
 ## New group
 
@@ -43,6 +45,7 @@ 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
 
@@ -54,7 +57,7 @@ POST  /groups/:id/projects/:project_id
 
 Parameters:
 
-- `id` (required) - The ID of a group
+- `id` (required) - The ID or path of a group
 - `project_id` (required) - The ID of a project
 
 ## Remove group
@@ -67,7 +70,26 @@ DELETE /groups/:id
 
 Parameters:
 
-- `id` (required) - The ID of a user group
+- `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
 
@@ -124,10 +146,24 @@ POST /groups/:id/members
 
 Parameters:
 
-- `id` (required) - The ID of a group
+- `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.
@@ -138,5 +174,5 @@ DELETE /groups/:id/members/:user_id
 
 Parameters:
 
-- `id` (required) - The ID of a user group
+- `id` (required) - The ID or path 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 ceeb683a6bf..5a2f6a4c229 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -18,6 +18,8 @@ Parameters:
 
 - `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`
 
 ```json
 [
@@ -56,7 +58,7 @@ Parameters:
       "title": "v1.0",
       "description": "",
       "due_date": "2012-07-20",
-      "state": "reopenend",
+      "state": "reopened",
       "updated_at": "2012-07-04T13:42:48Z",
       "created_at": "2012-07-04T13:42:48Z"
     },
@@ -105,6 +107,8 @@ Parameters:
 - `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`
 
 ## Single issue
 
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 14884e53915..1f3fd26a241 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -2,7 +2,9 @@
 
 ## List merge requests
 
-Get all merge requests for this project. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
+Get all merge requests for this project. 
+The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). 
+The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
 
 ```
 GET /projects/:id/merge_requests
@@ -14,8 +16,8 @@ Parameters:
 
 - `id` (required) - The ID of a project
 - `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed`
-- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order
+- `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
 [
@@ -94,6 +96,76 @@ Parameters:
 }
 ```
 
+## Get single MR changes
+
+Shows information about the merge request including its files and changes
+
+```
+GET /projects/:id/merge_request/:merge_request_id/changes
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - The ID of MR
+
+```json
+{
+  "id": 21,
+  "iid": 1,
+  "project_id": 4,
+  "title": "Blanditiis beatae suscipit hic assumenda et molestias nisi asperiores repellat et.",
+  "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.",
+  "state": "reopened",
+  "created_at": "2015-02-02T19:49:39.159Z",
+  "updated_at": "2015-02-02T20:08:49.959Z",
+  "target_branch": "secret_token",
+  "source_branch": "version-1-9",
+  "upvotes": 0,
+  "downvotes": 0,
+  "author": {
+    "name": "Chad Hamill",
+    "username": "jarrett",
+    "id": 5,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon"
+  },
+  "assignee": {
+    "name": "Administrator",
+    "username": "root",
+    "id": 1,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon"
+  },
+  "source_project_id": 4,
+  "target_project_id": 4,
+  "labels": [ ],
+  "milestone": {
+    "id": 5,
+    "iid": 1,
+    "project_id": 4,
+    "title": "v2.0",
+    "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
+    "state": "closed",
+    "created_at": "2015-02-02T19:49:26.013Z",
+    "updated_at": "2015-02-02T19:49:26.013Z",
+    "due_date": null
+  },
+  "files": [
+    {
+    "old_path": "VERSION",
+    "new_path": "VERSION",
+    "a_mode": "100644",
+    "b_mode": "100644",
+    "diff": "--- a/VERSION\ +++ b/VERSION\ @@ -1 +1 @@\ -1.9.7\ +1.9.8",
+    "new_file": false,
+    "renamed_file": false,
+    "deleted_file": false
+    }
+  ]
+}
+```
+
 ## Create MR
 
 Creates a new merge request.
@@ -109,6 +181,7 @@ Parameters:
 - `target_branch` (required)     - The target branch
 - `assignee_id` (optional)       - Assignee user ID
 - `title` (required)             - Title of MR
+- `description` (optional)       - Description of MR
 - `target_project_id` (optional) - The target project (numeric id)
 
 ```json
@@ -160,6 +233,7 @@ Parameters:
 - `target_branch`               - The target branch
 - `assignee_id`                 - Assignee user ID
 - `title`                       - Title of MR
+- `description`                 - Description of MR
 - `state_event`                 - New state (close|reopen|merge)
 
 ```json
@@ -169,6 +243,7 @@ Parameters:
   "source_branch": "test1",
   "project_id": 3,
   "title": "test1",
+  "description": "description1",
   "state": "opened",
   "upvotes": 0,
   "downvotes": 0,
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 2f525327504..d48b3bcce8a 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -72,3 +72,16 @@ Parameters:
 - `description` (optional) - The description of a milestone
 - `due_date` (optional) - The due date of the milestone
 - `state_event` (optional) - The state event of the milestone (close|activate)
+
+## Get all issues assigned to a single milestone
+
+Gets all issues assigned to a single project milestone.
+
+```
+GET /projects/:id/milestones/:milestone_id/issues
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `milestone_id` (required) - The ID of a project milestone
diff --git a/doc/api/notes.md b/doc/api/notes.md
index b5256ac803e..c22e493562a 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -78,6 +78,21 @@ Parameters:
 - `issue_id` (required) - The ID of an issue
 - `body` (required) - The content of a note
 
+### Modify existing issue note
+
+Modify existing note of an issue.
+
+```
+PUT /projects/:id/issues/:issue_id/notes/:note_id
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `issue_id` (required) - The ID of an issue
+- `note_id` (required) - The ID of a note
+- `body` (required) - The content of a note
+
 ## Snippets
 
 ### List all snippet notes
@@ -137,7 +152,22 @@ POST /projects/:id/snippets/:snippet_id/notes
 Parameters:
 
 - `id` (required) - The ID of a project
-- `snippet_id` (required) - The ID of an snippet
+- `snippet_id` (required) - The ID of a snippet
+- `body` (required) - The content of a note
+
+### Modify existing snippet note
+
+Modify existing note of a snippet.
+
+```
+PUT /projects/:id/snippets/:snippet_id/notes/:note_id
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `snippet_id` (required) - The ID of a snippet
+- `note_id` (required) - The ID of a note
 - `body` (required) - The content of a note
 
 ## Merge Requests
@@ -199,3 +229,18 @@ 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
+
+### Modify existing merge request note
+
+Modify existing note of a merge request.
+
+```
+PUT /projects/:id/merge_requests/:merge_request_id/notes/:note_id
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - The ID of a merge request
+- `note_id` (required) - The ID of a note
+- `body` (required) - The content of a note
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
new file mode 100644
index 00000000000..d416a826f79
--- /dev/null
+++ b/doc/api/oauth2.md
@@ -0,0 +1,102 @@
+# GitLab as an OAuth2 client
+
+This document is about using other OAuth authentication service providers to sign into GitLab.
+If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [Oauth2 provider documentation](../integration/oauth_provider.md).
+
+OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. 
+
+Before using the OAuth2 you should create an application in user's account. Each application gets a unique App ID and App Secret parameters. You should not share these.
+
+This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
+
+## Web Application Flow
+
+This flow is using for authentication from third-party web sites and is probably used the most. 
+It basically consists of an exchange of an authorization token for an access token. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)
+
+This flow consists from 3 steps.
+
+### 1. Registering the client
+
+Create an application in user's account profile.
+
+### 2. Requesting authorization
+
+To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that by visiting manually the URL:
+
+```
+http://localhost:3000/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code
+```
+
+Where REDIRECT_URI is the URL in your app where users will be sent after authorization. 	
+
+### 3. Requesting the access token
+
+To request the access token, you should use the returned code and exchange it for an access token. To do that you can use any HTTP client. In this case, I used rest-client:
+
+```
+parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI'
+RestClient.post 'http://localhost:3000/oauth/token', parameters
+
+# The response will be
+{
+ "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
+ "token_type": "bearer", 
+ "expires_in": 7200,
+ "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
+}
+```
+
+You can now make requests to the API with the access token returned.
+
+###  Use the access token to access the API
+
+The access token allows you to make requests to the API on a behalf of a user.
+
+```
+GET https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
+```
+
+Or you can put the token to the Authorization header:
+
+```
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
+```
+
+## Resource Owner Password Credentials
+
+In this flow, a token is requested in exchange for the resource owner credentials (username and password). 
+The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the
+client is part of the device operating system or a highly privileged application), and when other authorization grant types are not
+available (such as an authorization code).
+
+Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used
+for a single request and are exchanged for an access token.  This grant type can eliminate the need for the client to store the
+resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.
+You can do POST request to `/oauth/token` with parameters:
+
+```
+{
+  "grant_type"    : "password",
+  "username"      : "user@example.com",
+  "password"      : "sekret"
+}
+```
+
+Then, you'll receive the access token back in the response:
+
+```
+{
+  "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
+  "token_type": "bearer",
+  "expires_in": 7200
+}
+```
+
+For testing you can use the oauth2 ruby gem:
+
+```
+client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com")
+access_token = client.password.get_token('user@example.com', 'sekret')
+puts access_token.token
+```
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 0055e2e476f..a1a23051d7e 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,5 +1,23 @@
 # Projects
 
+
+### Project visibility level
+
+Project in GitLab has be either private, internal or public.
+You can determine it by `visibility_level` field in project. 
+
+Constants for project visibility levels are next:
+
+* Private. `visibility_level` is `0`. 
+  Project access must be granted explicitly for each user.
+
+* Internal. `visibility_level` is `10`.
+  The project can be cloned by any logged in user.
+ 
+* Public. `visibility_level` is `20`.
+  The project can be cloned without any authentication.
+
+
 ## List projects
 
 Get a list of projects accessible by the authenticated user.
@@ -11,6 +29,9 @@ GET /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
 
 ```json
 [
@@ -95,6 +116,13 @@ Get a list of projects which are owned by the authenticated user.
 GET /projects/owned
 ```
 
+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
+
 ### List ALL projects
 
 Get a list of all GitLab projects (admin only).
@@ -103,6 +131,13 @@ Get a list of all GitLab projects (admin only).
 GET /projects/all
 ```
 
+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
+
 ### Get single project
 
 Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user.
@@ -284,6 +319,31 @@ Parameters:
 - `visibility_level` (optional)
 - `import_url` (optional)
 
+### Edit project
+
+Updates an existing project
+
+```
+PUT /projects/:id
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `name` (optional) - project name
+- `path` (optional) - repository name for project
+- `description` (optional) - short project description
+- `default_branch` (optional)
+- `issues_enabled` (optional)
+- `merge_requests_enabled` (optional)
+- `wiki_enabled` (optional)
+- `snippets_enabled` (optional)
+- `public` (optional) - if `true` same as setting visibility_level = 20
+- `visibility_level` (optional)
+
+On success, method returns 200 with the updated project. If parameters are 
+invalid, 400 is returned.
+
 ### Fork project
 
 Forks a project into the user namespace of the authenticated user.
@@ -513,7 +573,7 @@ Parameters:
         }
       ],
       "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee",
-      "message": "give caolan credit where it's due (up top)",
+      "message": "give Caolan credit where it's due (up top)",
       "author": {
         "name": "Jeremy Ashkenas",
         "email": "jashkenas@example.com"
@@ -628,6 +688,8 @@ 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
+- `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
+- `order_by` (optional) - Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields
+- `sort` (optional) - Return requests sorted in `asc` or `desc` order
diff --git a/doc/api/services.md b/doc/api/services.md
index ab9f9c00c67..cbf767d1b25 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -13,7 +13,7 @@ PUT /projects/:id/services/gitlab-ci
 Parameters:
 
 - `token` (required) - CI project token
-- `project_url` (required) - CI project url
+- `project_url` (required) - CI project URL
 
 ### Delete GitLab CI service
 
@@ -23,23 +23,23 @@ Delete GitLab CI service settings for a project.
 DELETE /projects/:id/services/gitlab-ci
 ```
 
-## Hipchat
+## HipChat
 
-### Edit Hipchat service
+### Edit HipChat service
 
-Set Hipchat service for project.
+Set HipChat service for project.
 
 ```
 PUT /projects/:id/services/hipchat
 ```
 Parameters:
 
-- `token` (required) - Hipchat token
-- `room` (required) - Hipchat room name
+- `token` (required) - HipChat token
+- `room` (required) - HipChat room name
 
-### Delete Hipchat service
+### Delete HipChat service
 
-Delete Hipchat service for a project.
+Delete HipChat service for a project.
 
 ```
 DELETE /projects/:id/services/hipchat
diff --git a/doc/api/users.md b/doc/api/users.md
index fec5deebee4..a8b7685b503 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -78,7 +78,8 @@ GET /users
     "is_admin": false,
     "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
     "can_create_group": true,
-    "can_create_project": true
+    "can_create_project": true,
+    "projects_limit": 100
   }
 ]
 ```
@@ -140,7 +141,8 @@ Parameters:
   "color_scheme_id": 2,
   "is_admin": false,
   "can_create_group": true,
-  "can_create_project": true
+  "can_create_project": true,
+  "projects_limit": 100
 }
 ```
 
@@ -241,7 +243,8 @@ GET /user
   "color_scheme_id": 2,
   "is_admin": false,
   "can_create_group": true,
-  "can_create_project": true
+  "can_create_project": true,
+  "projects_limit": 100
 }
 ```
 
@@ -258,12 +261,14 @@ GET /user/keys
   {
     "id": 1,
     "title": "Public key",
-    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
+    "created_at": "2014-08-01T14:47:39.080Z"
   },
   {
     "id": 3,
     "title": "Another Public key",
-    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
+    "created_at": "2014-08-01T14:47:39.080Z"
   }
 ]
 ```
@@ -300,7 +305,8 @@ Parameters:
 {
   "id": 1,
   "title": "Public key",
-  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
+  "created_at": "2014-08-01T14:47:39.080Z"
 }
 ```
 
@@ -317,6 +323,31 @@ Parameters:
 - `title` (required) - new SSH Key's title
 - `key` (required)   - new SSH key
 
+```json
+{
+  "created_at": "2015-01-21T17:44:33.512Z",
+  "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
+  "title": "ABC",
+  "id": 4
+}
+```
+
+Will return created key with status `201 Created` on success. If an
+error occurs a `400 Bad Request` is returned with a message explaining the error:
+
+```json
+{
+  "message": {
+    "fingerprint": [
+      "has already been taken"
+    ],
+    "key": [
+      "has already been taken"
+    ]
+  }
+}
+```
+
 ## Add SSH key for user
 
 Create new key owned by specified user. Available only for admin