Refactor API documentation

Signed-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>

5 files changed, 284 insertions, 97 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
new file mode 100644
index 0000000..9e3a868
--- /dev/null
+++ b/doc/api/README.md
@@ -0,0 +1,86 @@
+# GitLab CI API
+
+## Resources
+
+- [Projects](projects.md)
+- [Runners](runners.md)
+- [Commits](commits.md)
+- [Builds](builds.md)
+
+
+## Authentication
+
+GitLab CI API uses different types of authentication depends on what API you use.
+Each API document has section with information about authentication you need to use.
+
+GitLab CI API has 4 authentication methods:
+
+* GitLab user token & GitLab url
+* GitLab CI project token
+* GitLab CI runners registration token
+* GitLab CI runner token
+
+
+### Authentication #1: GitLab user token & GitLab url
+
+Authentication is done by
+sending the `private-token` of a valid user and the `url` of an
+authorized Gitlab instance via a query string along with the API
+request:
+
+    GET http://ci.example.com/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
+
+If preferred, you may instead send the `private-token` as a header in
+your request:
+
+    curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://ci.example.com/api/v1/projects?url=http://demo.gitlab.com/"
+
+
+### Authentication #2: GitLab CI project token
+
+Each project in GitLab CI has it own token. 
+It can be used to get project commits and builds information.
+You can use project token only for certain project.
+
+### Authentication #3: GitLab CI runners registration token
+
+This token is not persisted and is generated on each application start.
+It can be used only for registering new runners in system. You can find it on 
+GitLab CI Runners web page https://gitlab-ci.example.com/admin/runners
+
+### Authentication #4: GitLab CI runner token
+
+Every GitLab CI runner has it own token that allow it to receive and update 
+GitLab CI builds. This token exists of internal purposes and should be used only 
+by runners
+
+## JSON
+
+All API requests are serialized using JSON.  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
+- `422 Unprocessable` - The entity could not be processed
+- `500 Server Error` - While handling the request something went wrong on the server side
diff --git a/doc/api/builds.md b/doc/api/builds.md
new file mode 100644
index 0000000..54749bc
--- /dev/null
+++ b/doc/api/builds.md
@@ -0,0 +1,41 @@
+# Builds API
+
+This API used by runners to receive and update builds.
+
+__Authentication is done by runner token__
+
+## Builds
+
+### Runs oldest pending build by runner
+
+    POST /builds/register
+
+Parameters:
+
+  * `token` (required) - The unique token of runner
+
+Returns:
+
+```json
+{
+  "id" : 79,
+  "commands" : "",
+  "path" : "",
+  "ref" : "",
+  "sha" : "",
+  "project_id" : 6,
+  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+  "before_sha" : ""
+}
+```
+
+
+### Update details of an existing build
+
+    PUT /builds/:id
+
+Parameters:
+
+  * `id` (required) - The ID of a project
+  * `state` (optional) - The state of a build
+  * `trace` (optional) - The trace of a build
diff --git a/doc/api/commits.md b/doc/api/commits.md
new file mode 100644
index 0000000..b348e23
--- /dev/null
+++ b/doc/api/commits.md
@@ -0,0 +1,105 @@
+# Commits API
+
+__Authentication is done by GitLab CI project token__
+
+## Commits
+
+### Retrieve all commits per project
+
+Get list of commits per project
+
+    GET /commits
+
+Parameters:
+
+  * `project_id` (required) - The ID of a project
+  * `project_token` (requires) - Project token
+  * `page` (optional)
+  * `per_page` (optional) - items per request (default is 20)
+
+Returns:
+
+```json
+[{
+  "id": 3,
+  "ref": "master",
+  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+  "project_id": 2,
+  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+  "created_at": "2014-11-05T09:46:35.247Z",
+  "status": "success",
+  "finished_at": "2014-11-05T09:46:44.254Z",
+  "duration": 5.062692165374756,
+  "git_commit_message": "wow\n",
+  "git_author_name": "Administrator",
+  "git_author_email": "admin@example.com",
+  "builds": [{
+    "id": 7,
+    "project_id": 2,
+    "ref": "master",
+    "status": "success",
+    "finished_at": "2014-11-05T09:46:44.254Z",
+    "created_at": "2014-11-05T09:46:35.259Z",
+    "updated_at": "2014-11-05T09:46:44.255Z",
+    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+    "started_at": "2014-11-05T09:46:39.192Z",
+    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+    "runner_id": 1,
+    "coverage": null,
+    "commit_id": 3,
+    "commands": "git submodule update --init\nls -la\n",
+    "job_id": 3
+  }]
+}]
+```
+
+### Create commit
+
+Inform GitLab CI about new commit you want it to build.
+
+__If commit already exists in GitLab CI it will not be created__
+
+
+    POST /commits
+
+Parameters:
+
+  * `project_id` (required) - The ID of a project
+  * `project_token` (requires) - Project token
+  * `data` (required) -  Push data. For example see comment in `lib/api/commits.rb`
+
+Returns:
+
+```json
+{
+  "id": 3,
+  "ref": "master",
+  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+  "project_id": 2,
+  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+  "created_at": "2014-11-05T09:46:35.247Z",
+  "status": "success",
+  "finished_at": "2014-11-05T09:46:44.254Z",
+  "duration": 5.062692165374756,
+  "git_commit_message": "wow\n",
+  "git_author_name": "Administrator",
+  "git_author_email": "admin@example.com",
+  "builds": [{
+    "id": 7,
+    "project_id": 2,
+    "ref": "master",
+    "status": "success",
+    "finished_at": "2014-11-05T09:46:44.254Z",
+    "created_at": "2014-11-05T09:46:35.259Z",
+    "updated_at": "2014-11-05T09:46:44.255Z",
+    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+    "started_at": "2014-11-05T09:46:39.192Z",
+    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+    "runner_id": 1,
+    "coverage": null,
+    "commit_id": 3,
+    "commands": "git submodule update --init\nls -la\n",
+    "job_id": 3
+  }]
+}
+```
diff --git a/doc/api/api.md b/doc/api/projects.md
index 0e0eed8..5086127 100644
--- a/doc/api/api.md
+++ b/doc/api/projects.md
@@ -1,24 +1,9 @@
-# Gitlab CI API
+# Projects API
 
 This API is intended to aid in the setup and configuration of
-projects, builds and runners on Gitlab CI.  Authentication is done by
-sending the `private-token` of a valid user and the `url` of an
-authorized Gitlab instance via a query string along with the API
-request:
+projects on Gitlab CI. 
 
-    GET http://ci.example.com/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
-
-If preferred, you may instead send the `private-token` as a header in
-your request:
-
-    curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://ci.example.com/api/v1/projects?url=http://demo.gitlab.com/"
-
-All API requests are serialized using JSON.  You don't need to specify
-`.json` at the end of API URL.
-
-# API Requests
-
-This lists all the requests that can be made via the API.
+__Authentication is done by GitLab user token & GitLab url__
 
 ## Projects
 
@@ -170,82 +155,3 @@ Parameters:
   * `id` (required) - The ID of the Gitlab CI project
   * `runner_id` (required) - The ID of the Gitlab CI runner
 
-## Runners
-
-### Retrieve all runners
-
-Used to get information about all runners registered on the Gitlab CI
-instance.
-
-    GET /runners
-
-Returns:
-
-```json
-[
-  {
-    "id" : 85,
-    "token" : "12b68e90394084703135"
-  },
-  {
-    "id" : 86,
-    "token" : "76bf894e969364709864"
-  },
-]
-```
-
-### Register a new runner
-
-Used to make Gitlab CI aware of available runners.
-
-    POST /runners/register
-
-Parameters:
-
-  * `token` (required) - The unique token of runner
-  * `public_key` (required) - Deploy key used to get projects
-
-Returns:
-
-```json
-{
-  "id" : 85,
-  "token" : "12b68e90394084703135"
-}
-```
-
-## Builds
-
-### Runs oldest pending build by runner
-
-    POST /builds/register
-
-Parameters:
-
-  * `token` (required) - The unique token of runner
-
-Returns:
-
-```json
-{
-  "id" : 79,
-  "commands" : "",
-  "path" : "",
-  "ref" : "",
-  "sha" : "",
-  "project_id" : 6,
-  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-  "before_sha" : ""
-}
-```
-
-
-### Update details of an existing build
-
-    PUT /builds/:id
-
-Parameters:
-
-  * `id` (required) - The ID of a project
-  * `state` (optional) - The state of a build
-  * `trace` (optional) - The trace of a build
diff --git a/doc/api/runners.md b/doc/api/runners.md
new file mode 100644
index 0000000..c82703c
--- /dev/null
+++ b/doc/api/runners.md
@@ -0,0 +1,49 @@
+# Runners API
+
+## Runners
+
+### Retrieve all runners
+
+__Authentication is done by GitLab user token & GitLab url__
+
+Used to get information about all runners registered on the Gitlab CI
+instance.
+
+    GET /runners
+
+Returns:
+
+```json
+[
+  {
+    "id" : 85,
+    "token" : "12b68e90394084703135"
+  },
+  {
+    "id" : 86,
+    "token" : "76bf894e969364709864"
+  },
+]
+```
+
+### Register a new runner
+
+
+__Authentication is done by GitLab CI runners registration token__
+
+Used to make Gitlab CI aware of available runners.
+
+    POST /runners/register
+
+Parameters:
+
+  * `token` (required) - The unique token of runner
+
+Returns:
+
+```json
+{
+  "id" : 85,
+  "token" : "12b68e90394084703135"
+}
+```