Merge branch 'doc/ci-api-update' into 'master'

Deprecated GitLab CI API clean up Deprecated GitLab CI API clean up. The intent here is to clean up deprecated GitLab CI documentation leaving only relevant information. Since we merged `Ci::Project` to `Project` most of this documentation is outdated. Closes #13610 See merge request !3003

Merge branch 'doc/ci-api-update' into 'master'
a19a9fab · Achilleas Pipinellis · 75a67ac0 · 74b96326 · a19a9fab · a19a9fab
Commit a19a9fab authored 9 years ago by Achilleas Pipinellis
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -213,8 +213,7 @@ Example response:
 ## Commit status
-Since GitLab 8.1, this is the new commit status API. The documentation in
+Since GitLab 8.1, this is the new commit status API.
-[ci/api/commits](../ci/api/commits.md) is deprecated.
 ### Get the status of a commit

--- a/doc/ci/api/README.md
+++ b/doc/ci/api/README.md
 # GitLab CI API
-## Resources
+## Purpose
- [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://gitlab.example.com/ci/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
-If preferred, you may instead send the `private-token` as a header in
+Main purpose of GitLab CI API is to provide necessary data and context for
-your request:
+GitLab CI Runners.
-    curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://gitlab.example.com/ci/api/v1/projects?url=http://demo.gitlab.com/"
+For consumer API take a look at this [documentation](../../api/README.md) where
+you will find all relevant information.
+## API Prefix
-### Authentication #2: GitLab CI project token
+Current CI API prefix is `/ci/api/v1`.
-Each project in GitLab CI has it own token. 
+You need to prepend this prefix to all examples in this documentation, like:
-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
+    GET /ci/api/v1/builds/:id/artifacts
-This token is not persisted and is generated on each application start.
+## Resources
-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
+- [Builds](builds.md)
- `201 Created` - The `POST` request was successful and the resource is returned as JSON
+- [Runners](runners.md)
- `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
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
 # Builds API
-This API used by runners to receive and update builds.
+API used by runners to receive and update builds.
-__Authentication is done by runner token__
+_**Note:** This API is intended to be used only by Runners as their own
+communication channel. For the consumer API see the
+[Builds API](../../api/builds.md)._
+## Authentication
+This API uses two types of authentication:
+1.   Unique runner's token
+     Token assigned to runner after it has been registered.
+2.   Using build authorization token
+     This is project's CI token that can be found in Continuous Integration
+     project settings.
+     Build authorization token can be passed as a parameter or a value of
+     `BUILD-TOKEN` header. This method are interchangeable.
 ## Builds
 ### Runs oldest pending build by runner
-    POST /ci/builds/register
+    POST /ci/api/v1/builds/register
 Parameters:
-  * `token` (required) - The unique token of runner
+  * `token` (required) - Unique runner token
-Returns:
-```json
-{
-  "id": 48584,
-  "ref": "0.1.1",
-  "tag": true,
-  "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
-  "status": "success",
-  "name": "pages",
-  "token": "9dd60b4f1a439d1765357446c1084c",
-  "stage": "test",
-  "project_id": 479,
-  "project_name": "test",
-  "commands": "echo commands",
-  "repo_url": "http://gitlab-ci-token:token@gitlab.example/group/test.git",
-  "before_sha": "0000000000000000000000000000000000000000",
-  "allow_git_fetch": false,
-  "options": {
-    "image": "docker:image",
-    "artifacts": {
-      "paths": [
-        "public"
-      ]
-    },
-    "cache": {
-      "paths": [
-        "vendor"
-      ]
-    }
-  },
-  "timeout": 3600,
-  "variables": [
-    {
-      "key": "CI_BUILD_TAG",
-      "value": "0.1.1",
-      "public": true
-    }
-  ],
-  "depends_on_builds": [
-    {
-      "id": 48584,
-      "ref": "0.1.1",
-      "tag": true,
-      "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
-      "status": "success",
-      "name": "build",
-      "token": "9dd60b4f1a439d1765357446c1084c",
-      "stage": "build",
-      "project_id": 479,
-      "project_name": "test",
-      "artifacts_file": {
-        "filename": "artifacts.zip",
-        "size": 0
-      }
-    }
-  ]
-}
-```
 ### Update details of an existing build
-    PUT /ci/builds/:id
+    PUT /ci/api/v1/builds/:id
 Parameters:
  * `id` (required) - The ID of a project
+  * `token` (required) - Unique runner token
  * `state` (optional) - The state of a build
  * `trace` (optional) - The trace of a build
+### Upload artifacts to build
+    POST /ci/api/v1/builds/:id/artifacts
+Parameters:
+  * `id` (required) - The ID of a build
+  * `token` (required) - The build authorization token
+  * `file` (required) - Artifacts file
+### Download the artifacts file from build
+    GET /ci/api/v1/builds/:id/artifacts
+Parameters:
+  * `id` (required) - The ID of a build
+  * `token` (required) - The build authorization token
+### Remove the artifacts file from build
+    DELETE /ci/api/v1/builds/:id/artifacts
+Parameters:
+  * ` id` (required) - The ID of a build
+  * `token` (required) - The build authorization token
--- a/doc/ci/api/commits.md
+++ b/doc/ci/api/commits.md
-# 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
-### Retrieve all commits per project
-Get list of commits per project
-    GET /ci/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
-  }]
-}]
-```
-### 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 /ci/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
-  }]
-}
-```
--- a/doc/ci/api/projects.md
+++ b/doc/ci/api/projects.md
-# Projects API
-This API is intended to aid in the setup and configuration of
-projects on GitLab CI.
-__Authentication is done by GitLab user token & GitLab url__
-## Projects
-### List Authorized Projects
-Lists all projects that the authenticated user has access to.
-```
-GET /ci/projects
-```
-Returns:
-```json
-[
-  {
-    "id" : 271,
-    "name" : "gitlabhq",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 3
-  },
-  {
-    "id" : 272,
-    "name" : "gitlab-ci",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 4
-  }
-]
-```
-### List Owned Projects
-Lists all projects that the authenticated user owns.
-```
-GET /ci/projects/owned
-```
-Returns:
-```json
-[
-  {
-    "id" : 272,
-    "name" : "gitlab-ci",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 4
-  }
-]
-```
-### Single Project
-Returns information about a single project for which the user is
-authorized.
-    GET /ci/projects/:id
-Parameters:
-  * `id` (required) - The ID of the GitLab CI project
-### Create Project
-Creates a GitLab CI project using GitLab project details.
-    POST /ci/projects
-Parameters:
-  * `name` (required) - The name of the project
-  * `gitlab_id` (required) - The ID of the project on the GitLab instance
-  * `default_ref` (optional) - The branch to run on (default to `master`)
-### Update Project
-Updates a GitLab CI project using GitLab project details that the
-authenticated user has access to.
-    PUT /ci/projects/:id
-Parameters:
-  * `name` - The name of the project
-  * `default_ref` - The branch to run on (default to `master`)
-### Remove Project
-Removes a GitLab CI project that the authenticated user has access to.
-    DELETE /ci/projects/:id
-Parameters:
-  * `id` (required) - The ID of the GitLab CI project
-### Link Project to Runner
-Links a runner to a project so that it can make builds (only via
-authorized user).
-    POST /ci/projects/:id/runners/:runner_id
-Parameters:
-  * `id` (required) - The ID of the GitLab CI project
-  * `runner_id` (required) - The ID of the GitLab CI runner
-### Remove Project from Runner
-Removes a runner from a project so that it can not make builds (only
-via authorized user).
-    DELETE /ci/projects/:id/runners/:runner_id
-Parameters:
-  * `id` (required) - The ID of the GitLab CI project
-  * `runner_id` (required) - The ID of the GitLab CI runner
\ No newline at end of file
--- a/doc/ci/api/runners.md
+++ b/doc/ci/api/runners.md
 # Runners API
+API used by runners to register and delete themselves.
 _**Note:** This API is intended to be used only by Runners as their own
 communication channel. For the consumer API see the
 [new Runners API](../../api/runners.md)._
-## Runners
+## Authentication
-### Retrieve all runners
-__Authentication is done by GitLab user token & GitLab url__
+This API uses two types of authentication:
-Used to get information about all runners registered on the GitLab CI
+1.   Unique runner's token
-instance.
-    GET /ci/runners
+     Token assigned to runner after it has been registered.
-Returns:
+2.   Using runners' registration token
-```json
+     This is a token that can be found in project's settings.
-[
+     It can be also found in Admin area &raquo; Runners settings.
-  {
-    "id" : 85,
-    "token" : "12b68e90394084703135"
-  },
-  {
-    "id" : 86,
-    "token" : "76bf894e969364709864"
-  },
-]
-```
-### Register a new runner
+     There are two types of tokens you can pass - shared runner registration
+     token or project specific registration token.
+## Runners
-__Authentication is done with a Shared runner registration token or a project Specific runner registration token__
+### Register a new runner
 Used to make GitLab CI aware of available runners.
-    POST /ci/runners/register
+    POST /ci/api/v1/runners/register
 Parameters:
-  * `token` (required) - The registration token. It is 2 types of token you can pass here. 
+  * `token` (required) - Registration token
-1. Shared runner registration token
-2. Project specific registration token
-Returns:
-```json
-{
-  "id" : 85,
-  "token" : "12b68e90394084703135"
-}
-```
 ### Delete a runner
+Used to remove runner.
-__Authentication is done by runner token__
+    DELETE /ci/api/v1/runners/delete
-Used to removing runners.
-    DELETE /ci/runners/delete
 Parameters:
-  * `token` (required) - The runner token.
+  * `token` (required) - Unique runner token
-Returns:
-```json
-{
-  "id" : 1,
-  "token" : "d14963981a428f70121777e50643d1",
-  "created_at" : "2015-02-26T11:39:39.232Z",
-  "updated_at" : "2015-02-26T11:39:39.232Z",
-  "description" : "awesome runner"
-}
-```