Merge branch 'doc_refactor_commits_api' into 'master'

Refactor commits API documentation

Blocked by https://gitlab.com/gitlab-org/gitlab-ce/issues/10960 which needs to be fixed or documented.

Closes #4217 

See merge request !2465

2 files changed, 188 insertions, 84 deletions

diff --git a/doc/api/commits.md b/doc/api/commits.md
index 93d62b751e6..e4d436b8e52 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 |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits"
+```
 
-- `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
+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,39 +158,65 @@ 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.
+
+In order to post a comment in a particular line of a particular file, you must
+specify the full commit SHA, the `path`, the `line` and `line_type` should be
+`new`.
+
+The comment will be added at the end of the last commit if at least one of the
+cases below is valid:
+
+- the `sha` is instead a branch or a tag and the `line` or `path` are invalid
+- the `line` number is invalid (does not exist)
+- the `path` is invalid (does not exist)
+
+In any of the above cases, the response of `line`, `line_type` and `path` is
+set to `null`.
 
 ```
 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 SHA or name of a repository branch or tag |
+| `note`      | string  | yes | The text of the comment |
+| `path`      | string  | no  | The file path relative to the repository |
+| `line`      | integer | no  | The line number where the comment should be placed |
+| `line_type` | string  | no  | The line type. Takes `new` or `old` as arguments |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "note=Nice picture man\!" -F "path=dudeism.md" -F "line=11" -F "line_type=new" https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments
+```
 
-- `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
 {
-  "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"
+   "author" : {
+      "web_url" : "https://gitlab.example.com/u/thedude",
+      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+      "username" : "thedude",
+      "state" : "active",
+      "name" : "Jeff Lebowski",
+      "id" : 28
+   },
+   "created_at" : "2016-01-19T09:44:55.600Z",
+   "line_type" : "new",
+   "path" : "dudeism.md",
+   "line" : 11,
+   "note" : "Nice picture man!"
 }
 ```
 
-## Get the status of a commit
+## Commit status
+
+Since GitLab 8.1, this is the new commit status API. The documentation in
+[ci/api/commits](../ci/api/commits.md) is deprecated.
+
+### Get the status of a commit
 
 Get the statuses of a commit in a project.
 
@@ -168,75 +224,116 @@ Get the statuses of a commit in a project.
 GET /projects/:id/repository/commits/:sha/statuses
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of a project
+| `sha`     | string  | yes | The commit SHA
+| `ref_name`| string  | no  | The name of a repository branch or tag or, if not given, the default branch
+| `stage`   | string  | no  | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test`
+| `name`    | string  | no  | Filter by [job name](../ci/yaml/README.md#jobs), e.g., `bundler:audit`
+| `all`     | boolean | no  | Return all statuses, not only the latest ones
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses
+```
 
-- `id` (required) - The ID of a project
-- `sha` (required) - The commit SHA
-- `ref` (optional) - Filter by ref name, it can be branch or tag
-- `stage` (optional) - Filter by stage
-- `name` (optional) - Filer by status name, eg. jenkins
-- `all` (optional) - The flag to return all statuses, not only latest ones
+Example response:
 
 ```json
 [
-  {
-    "id": 13,
-    "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
-    "ref": "test",
-    "status": "success",
-    "name": "ci/jenkins",
-    "target_url": "http://jenkins/project/url",
-    "description": "Jenkins success",
-    "created_at": "2015-10-12T09:47:16.250Z",
-    "started_at": "2015-10-12T09:47:16.250Z",
-    "finished_at": "2015-10-12T09:47:16.262Z",
-    "author": {
-      "id": 1,
-      "username": "admin",
-      "email": "admin@local.host",
-      "name": "Administrator",
-      "blocked": false,
-      "created_at": "2012-04-29T08:46:00Z"
-    }
-  }
+   ...
+
+   {
+      "status" : "pending",
+      "created_at" : "2016-01-19T08:40:25.934Z",
+      "started_at" : null,
+      "name" : "bundler:audit",
+      "allow_failure" : true,
+      "author" : {
+         "username" : "thedude",
+         "state" : "active",
+         "web_url" : "https://gitlab.example.com/u/thedude",
+         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+         "id" : 28,
+         "name" : "Jeff Lebowski"
+      },
+      "description" : null,
+      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+      "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/91",
+      "finished_at" : null,
+      "id" : 91,
+      "ref" : "master"
+   },
+   {
+      "started_at" : null,
+      "name" : "flay",
+      "allow_failure" : false,
+      "status" : "pending",
+      "created_at" : "2016-01-19T08:40:25.832Z",
+      "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/90",
+      "id" : 90,
+      "finished_at" : null,
+      "ref" : "master",
+      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+      "author" : {
+         "id" : 28,
+         "name" : "Jeff Lebowski",
+         "username" : "thedude",
+         "web_url" : "https://gitlab.example.com/u/thedude",
+         "state" : "active",
+         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"
+      },
+      "description" : null
+   },
+
+   ...
 ]
 ```
 
-## Post the status to commit
+### Post the build status to a commit
 
-Adds or updates a status of a commit.
+Adds or updates a build status of a commit.
 
 ```
 POST /projects/:id/statuses/:sha
 ```
 
-- `id` (required) - The ID of a project
-- `sha` (required) - The commit SHA
-- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled
-- `ref` (optional) - The ref (branch or tag) to which the status refers
-- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default"
-- `target_url` (optional) - The target URL to associate with this status
-- `description` (optional) - The short description of the status
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project
+| `sha`     | string  | yes   | The commit SHA
+| `state`   | string  | yes   | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled`
+| `ref`     | string  | no    | The `ref` (branch or tag) to which the status refers
+| `name` or `context` | string  | no | The label to differentiate this status from the status of other systems. Default value is `default`
+| `target_url` |  string  | no  | The target URL to associate with this status
+| `description` | string  | no  | The short description of the status
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
+```
+
+Example response:
 
 ```json
 {
-  "id": 13,
-  "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
-  "ref": "test",
-  "status": "success",
-  "name": "ci/jenkins",
-  "target_url": "http://jenkins/project/url",
-  "description": "Jenkins success",
-  "created_at": "2015-10-12T09:47:16.250Z",
-  "started_at": "2015-10-12T09:47:16.250Z",
-  "finished_at": "2015-10-12T09:47:16.262Z",
-  "author": {
-    "id": 1,
-    "username": "admin",
-    "email": "admin@local.host",
-    "name": "Administrator",
-    "blocked": false,
-    "created_at": "2012-04-29T08:46:00Z"
-  }
+   "author" : {
+      "web_url" : "https://gitlab.example.com/u/thedude",
+      "name" : "Jeff Lebowski",
+      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+      "username" : "thedude",
+      "state" : "active",
+      "id" : 28
+   },
+   "name" : "default",
+   "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+   "status" : "success",
+   "description" : null,
+   "id" : 93,
+   "target_url" : null,
+   "ref" : null,
+   "started_at" : null,
+   "created_at" : "2016-01-19T09:05:50.355Z",
+   "allow_failure" : false,
+   "finished_at" : "2016-01-19T09:05:50.365Z"
 }
 ```
diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md
index 4df7afc6c52..871de7abcce 100644
--- a/doc/ci/api/commits.md
+++ b/doc/ci/api/commits.md
@@ -1,5 +1,12 @@
 # Commits API
 
+**DEPRECATED**
+
+Since GitLab 8.1, there is a new commit status API. Please see the [revised
+documentation](../../api/commits.md#commit-status).
+
+---
+
 __Authentication is done by GitLab CI project token__
 
 ## Commits