From 68755a2397de4534d55002ad602e42051a461866 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 08:21:01 +0100 Subject: Refactor branches API documentation [ci skip] --- doc/api/branches.md | 108 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 73 insertions(+), 35 deletions(-) (limited to 'doc/api') diff --git a/doc/api/branches.md b/doc/api/branches.md index 6a9c10c8520..abc4732c395 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically. GET /projects/:id/repository/branches ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | -- `id` (required) - The ID of a project +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches +``` + +Example response: ```json [ { + "name": "master", + "protected": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -27,10 +35,9 @@ Parameters: "parent_ids": [ "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] - }, - "name": "master", - "protected": true - } + } + }, + ... ] ``` @@ -42,13 +49,21 @@ Get a single project repository branch. GET /projects/:id/repository/branches/:branch ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master +``` + +Example response: ```json { + "name": "master", + "protected": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -61,25 +76,30 @@ Parameters: "parent_ids": [ "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] - }, - "name": "master", - "protected": true + } } ``` ## Protect 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. +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 ``` -Parameters: +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/protect +``` -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | + +Example response: ```json { @@ -103,17 +123,24 @@ Parameters: ## 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. +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 ``` -Parameters: +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +Example response: ```json { @@ -141,11 +168,17 @@ Parameters: POST /projects/:id/repository/branches ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch_name` | string | yes | The name of the branch | +| `ref` | string | yes | The branch name or commit SHA to create branch from | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master" +``` -- `id` (required) - The ID of a project -- `branch_name` (required) - The name of the branch -- `ref` (required) - Create branch from commit SHA or existing branch +Example response: ```json { @@ -162,12 +195,13 @@ Parameters: "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] }, - "name": "master", + "name": "newbranch", "protected": false } ``` -It return 200 if succeed or 400 if failed with error message explaining reason. +It returns `200` if it succeeds or `400` if failed with an error message +explaining the reason. ## Delete repository branch @@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason. DELETE /projects/:id/repository/branches/:branch ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +It returns `200` if it succeeds, `404` if the branch to be deleted does not exist +or `400` for other reasons. In case of an error, an explaining message is provided. -It return 200 if succeed, 404 if the branch to be deleted does not exist -or 400 for other reasons. In case of an error, an explaining message is provided. +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch" +``` -Success response: +Example response: ```json { - "branch_name": "my-removed-branch" + "branch_name": "newbranch" } ``` -- cgit v1.2.1 From c870bb796bbbc424fdd369c8237b08b706215d03 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 08:25:38 +0100 Subject: Refactor commits API documentation [ci skip] --- doc/api/commits.md | 74 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 57 insertions(+), 17 deletions(-) (limited to 'doc/api') diff --git a/doc/api/commits.md b/doc/api/commits.md index 93d62b751e6..a07c9dff54e 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 | -- `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 +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits" +``` + +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,20 +158,30 @@ 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. Optionally you can post comments on a specific line +of a commit. In that case `path`, `line` and `line_type` are required. ``` 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 hash or name of a repository branch or tag | +| `note` | string | yes | Text of comment | +| `path` | string | no | The file path relative to the repository | +| `line` | integer | no | The line number | +| `line_type` | string | no | The line type. Takes `new` or `old` as arguments | + +In order to post a comment in a particular line of a particular file, you must +specify `path`, `line` and `line_type` should be `new`. + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments?note=New%20comment&path=CHANGELOG&line=664&line_type=new" +``` -- `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 { -- cgit v1.2.1 From 13f52de0fa0585df0da0d0579899be86e4bfe1c9 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:10:46 +0100 Subject: Refactor issues API documentation [ci skip] --- doc/api/issues.md | 404 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 260 insertions(+), 144 deletions(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index d407bc35d79..9e704648b25 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,9 +1,20 @@ # Issues +Every API call to issues must be authenticated. + +If a user is not a member of a project and the project is private, a `GET` +request on that project will result to a `404` status code. + +## Issues pagination + +By default, `GET` requests return 20 results at a time because the API results +are paginated. + +Read more on [pagination](README.md#pagination). + ## List issues -Get all issues created by authenticated user. This function takes pagination parameters -`page` and `per_page` to restrict the list of issues. +Get all issues created by the authenticated user. ``` GET /issues @@ -14,81 +25,65 @@ GET /issues?labels=foo,bar GET /issues?labels=foo,bar&state=opened ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `state` | string | no | Return all issues or just those that are `opened` or `closed`| +| `labels` | string | no | Comma-separated list of label names | +| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/issues +``` -- `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` +Example response: ```json [ - { - "id": 43, - "iid": 3, - "project_id": 8, - "title": "4xx/5xx pages", - "description": "", - "labels": [], - "milestone": null, - "assignee": null, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "closed", - "updated_at": "2012-07-02T17:53:12Z", - "created_at": "2012-07-02T17:53:12Z" - }, - { - "id": 42, - "iid": 4, - "project_id": 8, - "title": "Add user settings", - "description": "", - "labels": [ - "feature" - ], - "milestone": { - "id": 1, - "title": "v1.0", - "description": "", - "due_date": "2012-07-20", - "state": "reopened", - "updated_at": "2012-07-04T13:42:48Z", - "created_at": "2012-07-04T13:42:48Z" - }, - "assignee": { - "id": 2, - "username": "jack_smith", - "email": "jack@example.com", - "name": "Jack Smith", - "state": "active", - "created_at": "2012-05-23T08:01:01Z" - }, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "opened", - "updated_at": "2012-07-12T13:43:19Z", - "created_at": "2012-06-28T12:58:06Z" - } + { + "state" : "opened", + "description" : "Ratione dolores corrupti mollitia soluta quia.", + "author" : { + "state" : "active", + "id" : 18, + "web_url" : "https://gitlab.example.com/u/eileen.lowe", + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "username" : "eileen.lowe" + }, + "milestone" : { + "project_id" : 1, + "description" : "Ducimus nam enim ex consequatur cumque ratione.", + "state" : "closed", + "due_date" : null, + "iid" : 2, + "created_at" : "2016-01-04T15:31:39.996Z", + "title" : "v4.0", + "id" : 17, + "updated_at" : "2016-01-04T15:31:39.996Z" + }, + "project_id" : 1, + "assignee" : { + "state" : "active", + "id" : 1, + "name" : "Administrator", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root" + }, + "updated_at" : "2016-01-04T15:31:51.081Z", + "id" : 76, + "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.", + "created_at" : "2016-01-04T15:31:51.081Z", + "iid" : 6, + "labels" : [] + }, ] ``` ## List 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 a list of a project's issues. ``` GET /projects/:id/issues @@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iid=42 ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `iid` | integer | no | Return the issue having the given `iid` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed`| +| `labels` | string | no | Comma-separated list of label names | +| `milestone` | string| no | The milestone title | +| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | + + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues +``` + +Example response: -- `id` (required) - The ID of a project -- `iid` (optional) - Return the issue having the given `iid` -- `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` +```json +[ + { + "project_id" : 4, + "milestone" : { + "due_date" : null, + "project_id" : 4, + "state" : "closed", + "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid" : 3, + "id" : 11, + "title" : "v3.0", + "created_at" : "2016-01-04T15:31:39.788Z", + "updated_at" : "2016-01-04T15:31:39.788Z" + }, + "author" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "state" : "closed", + "iid" : 1, + "assignee" : { + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/u/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }, + "labels" : [], + "id" : 41, + "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at" : "2016-01-04T15:31:46.176Z", + "created_at" : "2016-01-04T15:31:46.176Z" + } +] +``` ## Single issue -Gets a single project issue. +Get a single project issue. ``` GET /projects/:id/issues/:issue_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id`| integer | yes | The ID of a project's issue | -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41 +``` + +Example response: ```json { - "id": 42, - "iid": 3, - "project_id": 8, - "title": "Add user settings", - "description": "", - "labels": [ - "feature" - ], - "milestone": { - "id": 1, - "title": "v1.0", - "description": "", - "due_date": "2012-07-20", - "state": "closed", - "updated_at": "2012-07-04T13:42:48Z", - "created_at": "2012-07-04T13:42:48Z" - }, - "assignee": { - "id": 2, - "username": "jack_smith", - "email": "jack@example.com", - "name": "Jack Smith", - "state": "active", - "created_at": "2012-05-23T08:01:01Z" - }, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "opened", - "updated_at": "2012-07-12T13:43:19Z", - "created_at": "2012-06-28T12:58:06Z" + "project_id" : 4, + "milestone" : { + "due_date" : null, + "project_id" : 4, + "state" : "closed", + "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid" : 3, + "id" : 11, + "title" : "v3.0", + "created_at" : "2016-01-04T15:31:39.788Z", + "updated_at" : "2016-01-04T15:31:39.788Z" + }, + "author" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "state" : "closed", + "iid" : 1, + "assignee" : { + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/u/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }, + "labels" : [], + "id" : 41, + "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at" : "2016-01-04T15:31:46.176Z", + "created_at" : "2016-01-04T15:31:46.176Z" } ``` @@ -170,57 +221,122 @@ Parameters: Creates a new project issue. +If the operation is successful, a status code of `200` and the newly-created +issue is returned. If an error occurs, an error number and a message explaining +the reason is returned. + ``` POST /projects/:id/issues ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug +``` -- `id` (required) - The ID of a project -- `title` (required) - The title of an issue -- `description` (optional) - The description of an issue -- `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 +Example response: -If the operation is successful, 200 and the newly created issue is returned. -If an error occurs, an error number and a message explaining the reason is returned. +```json +{ + "project_id" : 4, + "id" : 84, + "created_at" : "2016-01-07T12:44:33.959Z", + "iid" : 14, + "title" : "Issues with auth", + "state" : "opened", + "assignee" : null, + "labels" : [ + "bug" + ], + "author" : { + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "state" : "active", + "web_url" : "https://gitlab.example.com/u/eileen.lowe", + "id" : 18, + "username" : "eileen.lowe" + }, + "description" : null, + "updated_at" : "2016-01-07T12:44:33.959Z", + "milestone" : null +} +``` ## Edit issue -Updates an existing project issue. This function is also used to mark an issue as closed. +Updates an existing project issue. This call is also used to mark an issue as +closed. + +If the operation is successful, a code of `200` and the updated issue is +returned. If an error occurs, an error number and a message explaining the +reason is returned. ``` PUT /projects/:id/issues/:issue_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of a project's issue | +| `title` | string | no | The title of an issue | +| `description` | string | no | The description of an issue | +| `assignee_id` | integer | no | The ID of a user to assign the issue to | +| `milestone_id` | integer | no | The ID of a milestone to assign the issue to | +| `labels` | string | no | Comma-separated label names for an issue | +| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/85?state_event=close +``` -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project's issue -- `title` (optional) - The title of an issue -- `description` (optional) - The description of an issue -- `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 -- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it) +Example response: -If the operation is successful, 200 and the updated issue is returned. -If an error occurs, an error number and a message explaining the reason is returned. +```json +{ + "created_at" : "2016-01-07T12:46:01.410Z", + "author" : { + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "username" : "eileen.lowe", + "id" : 18, + "state" : "active", + "web_url" : "https://gitlab.example.com/u/eileen.lowe" + }, + "state" : "closed", + "title" : "Issues with auth", + "project_id" : 4, + "description" : null, + "updated_at" : "2016-01-07T12:55:16.213Z", + "iid" : 15, + "labels" : [ + "bug" + ], + "id" : 85, + "assignee" : null, + "milestone" : null +} +``` ## 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 `state_event` set to `close`. +This call 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 the parameter `state_event` set to +`close`. See [edit issue](#edit-issue) for more details. ``` DELETE /projects/:id/issues/:issue_id ``` -Parameters: - -- `id` (required) - The project ID -- `issue_id` (required) - The ID of the issue - ## Comments on issues -Comments are done via the notes resource. +Comments are done via the [notes](notes.md) resource. -- cgit v1.2.1 From cfb0628d76575ea1ae8671e7e3d8896fbf38a5c8 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:16:14 +0100 Subject: Refactor deploy_keys API documentation [ci skip] --- doc/api/deploy_keys.md | 74 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 12 deletions(-) (limited to 'doc/api') diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index e4492fc609c..9da1fe22e61 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -8,9 +8,15 @@ Get a list of a project's deploy keys. GET /projects/:id/keys ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys" +``` -- `id` (required) - The ID of the project +Example response: ```json [ @@ -39,8 +45,16 @@ GET /projects/:id/keys/:key_id Parameters: -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `key_id` | integer | yes | The ID of the deploy key | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/11" +``` + +Example response: ```json { @@ -54,17 +68,34 @@ Parameters: ## 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 + +If the deploy key already exists in another project, it will be joined to current +project only if original one was is accessible by the same user. ``` POST /projects/:id/keys ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `title` | string | yes | New deploy key's title | +| `key` | string | yes | New deploy key | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v3/projects/5/keys/" +``` -- `id` (required) - The ID of the project -- `title` (required) - New deploy key's title -- `key` (required) - New deploy key +Example response: + +```json +{ + "key" : "ssh-rsa AAAA...", + "id" : 12, + "title" : "My deploy key", + "created_at" : "2015-08-29T12:44:31.550Z" +} +``` ## Delete deploy key @@ -74,7 +105,26 @@ Delete a deploy key from a project DELETE /projects/:id/keys/:key_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `key_id` | integer | yes | The ID of the deploy key | + +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/13" +``` -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key +Example response: + +```json +{ + "updated_at" : "2015-08-29T12:50:57.259Z", + "key" : "ssh-rsa AAAA...", + "public" : false, + "title" : "My deploy key", + "user_id" : null, + "created_at" : "2015-08-29T12:50:57.259Z", + "fingerprint" : "6a:33:1f:74:51:c0:39:81:79:ec:7a:31:f8:40:20:43", + "id" : 13 +} +``` -- cgit v1.2.1 From 981a6865f2fa6185eb3f9bc746f5fb60badf8f09 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:41:42 +0100 Subject: Refactor labels API documentation [ci skip] --- doc/api/labels.md | 152 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 111 insertions(+), 41 deletions(-) (limited to 'doc/api') diff --git a/doc/api/labels.md b/doc/api/labels.md index de41f35d284..6496ffe9fd1 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -2,83 +2,153 @@ ## List labels -Get all labels for given project. +Get all labels for a given project. ``` GET /projects/:id/labels ``` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels +``` + +Example response: + ```json [ - { - "name": "Awesome", - "color": "#DD10AA" - }, - { - "name": "Documentation", - "color": "#1E80DD" - }, - { - "name": "Feature", - "color": "#11FF22" - }, - { - "name": "Bug", - "color": "#EE1122" - } + { + "name" : "bug", + "color" : "#d9534f" + }, + { + "color" : "#d9534f", + "name" : "confirmed" + }, + { + "name" : "critical", + "color" : "#d9534f" + }, + { + "color" : "#428bca", + "name" : "discussion" + }, + { + "name" : "documentation", + "color" : "#f0ad4e" + }, + { + "color" : "#5cb85c", + "name" : "enhancement" + }, + { + "color" : "#428bca", + "name" : "suggestion" + }, + { + "color" : "#f0ad4e", + "name" : "support" + } ] ``` ## Create a new label -Creates a new label for given repository with given name and color. +Creates a new label for the given repository with the given name and color. + +It returns 200 if the label was successfully created, 400 for wrong parameters +and 409 if the label already exists. ``` POST /projects/:id/labels ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the label | +| `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign | + +```bash +curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" +``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the label -- `color` (required) - Color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) +Example response: -It returns 200 and the newly created label, if the operation succeeds. -If the label already exists, 409 and an error message is returned. -If label parameters are invalid, 400 and an explaining error message is returned. +```json +{ + "name" : "feature", + "color" : "#5843AD" +} +``` ## Delete a label -Deletes a label given by its name. +Deletes a label with a given name. + +It returns 200 if the label was successfully deleted, 400 for wrong parameters +and 404 if the label does not exist. +In case of an error, an additional error message is returned. ``` DELETE /projects/:id/labels ``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the label to be deleted +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the label | -It returns 200 if the label successfully was deleted, 400 for wrong parameters -and 404 if the label does not exist. -In case of an error, additionally an error message is returned. +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug" +``` + +Example response: + +```json +{ + "title" : "feature", + "color" : "#5843AD", + "updated_at" : "2015-11-03T21:22:30.737Z", + "template" : false, + "project_id" : 1, + "created_at" : "2015-11-03T21:22:30.737Z", + "id" : 9 +} +``` ## Edit an existing label -Updates an existing label with new name or now color. At least one parameter +Updates an existing label with new name or new color. At least one parameter is required, to update the label. +It returns 200 if the label was successfully deleted, 400 for wrong parameters +and 404 if the label does not exist. +In case of an error, an additional error message is returned. + ``` PUT /projects/:id/labels ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the existing label | +| `new_name` | string | yes if `color` if not provided | The new name of the label | +| `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign | + +```bash +curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" +``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the existing label -- `new_name` (optional) - The new name of the label -- `color` (optional) - New color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) +Example response: -On success, this method returns 200 with the updated label. -If required parameters are missing or parameters are invalid, 400 is returned. -If the label to be updated is missing, 404 is returned. -In case of an error, additionally an error message is returned. +```json +{ + "color" : "#8E44AD", + "name" : "docs" +} +``` -- cgit v1.2.1 From ddc8b91a5f89c1bd1b4bed955231ae286420d9d2 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:42:44 +0100 Subject: Refactor namespaces API documentation [ci skip] --- doc/api/namespaces.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'doc/api') diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 7b3238441f6..68ed8bd3152 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,13 +1,22 @@ # Namespaces +Namespaces account for usernames and groupnames. + +[Pagination](README.md#pagination) is used. + ## List namespaces -Get a list of namespaces. (As user: my namespaces, as admin: all namespaces) +Get a list of namespaces. As a user, your namespaces are listed whereas if you +are an administrator you get a list of all namespaces in the GitLab instance. ``` GET /namespaces ``` +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces +``` + ```json [ { @@ -23,22 +32,28 @@ GET /namespaces ] ``` -You can search for namespaces by name or path, see below. - ## Search for namespace -Get all namespaces that match your string in their name or path. +Get all namespaces that match a string in their name or path. ``` GET /namespaces?search=foobar ``` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `search` | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter +``` + ```json [ { - "id": 1, - "path": "user1", - "kind": "user" + "id": 4, + "path": "twitter", + "kind": "group" } ] ``` -- cgit v1.2.1 From 585e7f6e35c8b40ac1d79b06da399bbff7181bdc Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:44:19 +0100 Subject: Refactor settings API documentation [ci skip] --- doc/api/settings.md | 98 +++++++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 44 deletions(-) (limited to 'doc/api') diff --git a/doc/api/settings.md b/doc/api/settings.md index 96867c67915..001de76c7af 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,67 +1,77 @@ # Application settings -This API allows you to read and modify GitLab instance application settings. +These API calls allow you to read and modify GitLab instance application +settings as appear in `/admin/application_settings`. You have to be an +administrator in order to perform this action. +## Get current application settings -## Get current application settings: +List the current application settings of the GitLab instance. ``` GET /application/settings ``` +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings +``` + +Example response: + ```json { - "id": 1, - "default_projects_limit": 10, - "signup_enabled": true, - "signin_enabled": true, - "gravatar_enabled": true, - "sign_in_text": "", - "created_at": "2015-06-12T15:51:55.432Z", - "updated_at": "2015-06-30T13:22:42.210Z", - "home_page_url": "", - "default_branch_protection": 2, - "twitter_sharing_enabled": true, - "restricted_visibility_levels": [], - "max_attachment_size": 10, - "session_expire_delay": 10080, - "default_project_visibility": 0, - "default_snippet_visibility": 0, - "restricted_signup_domains": [], - "user_oauth_applications": true, - "after_sign_out_path": "" + "default_projects_limit" : 10, + "signup_enabled" : true, + "id" : 1, + "default_branch_protection" : 2, + "restricted_visibility_levels" : [], + "signin_enabled" : true, + "twitter_sharing_enabled" : true, + "after_sign_out_path" : null, + "max_attachment_size" : 10, + "user_oauth_applications" : true, + "updated_at" : "2016-01-04T15:44:55.176Z", + "session_expire_delay" : 10080, + "home_page_url" : null, + "default_snippet_visibility" : 0, + "restricted_signup_domains" : [], + "created_at" : "2016-01-04T15:44:55.176Z", + "default_project_visibility" : 0, + "gravatar_enabled" : true, + "sign_in_text" : null } ``` -## Change application settings: - - +## Change application settings ``` PUT /application/settings ``` -Parameters: - -- `default_projects_limit` - project limit per user -- `signup_enabled` - enable registration -- `signin_enabled` - enable login via GitLab account -- `gravatar_enabled` - enable gravatar -- `sign_in_text` - text on login page -- `home_page_url` - redirect to this URL when not logged in -- `default_branch_protection` - determine if developers can push to master -- `twitter_sharing_enabled` - allow users to share project creation in twitter -- `restricted_visibility_levels` - restrict certain visibility levels -- `max_attachment_size` - limit attachment size -- `session_expire_delay` - session lifetime -- `default_project_visibility` - what visibility level new project receives -- `default_snippet_visibility` - what visibility level new snippet receives -- `restricted_signup_domains` - force people to use only corporate emails for signup -- `user_oauth_applications` - allow users to create oauth applications -- `after_sign_out_path` - where redirect user after logout +| Attribute | Type | Required | Description | +| --------- | ---- | :------: | ----------- | +| `default_projects_limit` | integer | no | Project limit per user. Default is `10` | +| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | +| `signin_enabled` | boolean | no | Enable login via a GitLab account. Default is `true`. | +| `gravatar_enabled` | boolean | no | Enable Gravatar | +| `sign_in_text` | string | no | Text on login page | +| `home_page_url` | string | no | Redirect to this URL when not logged in | +| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `1`. | +| `twitter_sharing_enabled` | boolean | no | Allow users to share project creation on Twitter | +| `restricted_visibility_levels` | array of integers | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is null which means there is no restriction. | +| `max_attachment_size` | integer | no | Limit attachment size in MB | +| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | +| `default_project_visibility` | integer | no | What visibility level new projects receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.| +| `default_snippet_visibility` | integer | no | What visibility level new snippets receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.| +| `restricted_signup_domains` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. | +| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider | +| `after_sign_out_path` | string | no | Where to redirect users after logout | -All parameters are optional. You can send only one that you want to change. +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings?signup_enabled=false&default_project_visibility=1 +``` +Example response: ```json { @@ -79,7 +89,7 @@ All parameters are optional. You can send only one that you want to change. "restricted_visibility_levels": [], "max_attachment_size": 10, "session_expire_delay": 10080, - "default_project_visibility": 0, + "default_project_visibility": 1, "default_snippet_visibility": 0, "restricted_signup_domains": [], "user_oauth_applications": true, -- cgit v1.2.1 From 3db8cfefc79de501aefc447d8f4360b9f6656196 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:45:50 +0100 Subject: Refactor system_hooks API documentation [ci skip] --- doc/api/system_hooks.md | 96 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 23 deletions(-) (limited to 'doc/api') diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index f9637d8a6c4..f539f64488b 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -2,39 +2,58 @@ All methods require admin authorization. -The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks). +The URL endpoint of the system hooks can also be configured using the UI in +[the admin area under hooks](/admin/hooks). ## List system hooks -Get list of system hooks +Get a list of all system hooks. ``` GET /hooks ``` -Parameters: +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks +``` -- **none** +Example response: ```json [ - { - "id": 3, - "url": "http://example.com/hook", - "created_at": "2013-10-02T10:15:31Z" - } + { + "id" : 1, + "url" : "https://gitlab.example.com/hook", + "created_at" : "2015-11-04T20:07:35.874Z" + } ] ``` -## Add new system hook hook +## Add new system hook ``` POST /hooks ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `url` | string | yes | The hook URL | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook" +``` -- `url` (required) - The hook URL +Example response: + +```json +[ + { + "id" : 2, + "url" : "https://gitlab.example.com/hook", + "created_at" : "2015-11-04T20:07:35.874Z" + } +] +``` ## Test system hook @@ -42,29 +61,60 @@ Parameters: GET /hooks/:id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the hook | -- `id` (required) - The ID of hook +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 +``` + +Example response: ```json { - "event_name": "project_create", - "name": "Ruby", - "path": "ruby", - "project_id": 1, - "owner_name": "Someone", - "owner_email": "example@gitlabhq.com" + "project_id" : 1, + "owner_email" : "example@gitlabhq.com", + "owner_name" : "Someone", + "name" : "Ruby", + "path" : "ruby", + "event_name" : "project_create" } ``` ## 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. +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 a JSON object is +returned. ``` DELETE /hooks/:id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the hook | + +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 +``` + +Example response: -- `id` (required) - The ID of hook +```json +{ + "note_events" : false, + "project_id" : null, + "enable_ssl_verification" : true, + "url" : "https://gitlab.example.com/hook", + "updated_at" : "2015-11-04T20:12:15.931Z", + "issues_events" : false, + "merge_requests_events" : false, + "created_at" : "2015-11-04T20:12:15.931Z", + "service_id" : null, + "id" : 2, + "push_events" : true, + "tag_push_events" : false +} +``` -- cgit v1.2.1 From 9eeda3da3dfa3b1e328ab139bd2b0a389dea5ef1 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:48:19 +0100 Subject: Remove relative link It wouldn't work on doc.gitlab.com [ci skip] --- doc/api/system_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index f539f64488b..b605f3540f3 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -3,7 +3,7 @@ All methods require admin authorization. The URL endpoint of the system hooks can also be configured using the UI in -[the admin area under hooks](/admin/hooks). +the admin area under hooks(`/admin/hooks`). ## List system hooks -- cgit v1.2.1 From 60752b6ec8d6a3a9ba368a66a69ea7e93bb104ef Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 10:10:33 +0100 Subject: Refactor README API documentation [ci skip] --- doc/api/README.md | 244 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 147 insertions(+), 97 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 2fa177ff4dd..51cd67f47f1 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -27,16 +27,15 @@ - [Build triggers](build_triggers.md) - [Build Variables](build_variables.md) -## 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 +## Authentication -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. +All API requests require authentication. You need to pass a `private_token` +parameter by URL or header. If passed as a 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 account page (`/profile/account`). -If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401: +If `private_token` is invalid or omitted, then an error message will be +returned with status code `401`: ```json { @@ -44,71 +43,82 @@ If no, or an invalid, `private_token` is provided then an error message will be } ``` -API requests should be prefixed with `api` and the API version. The API version is defined in `lib/api.rb`. +API requests should be prefixed with `api` and the API version. The API version +is defined in `lib/api.rb`. Example of a valid API request: -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U +```shell +GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK ``` -Example for a valid API request using curl and authentication via header: +Example of a valid API request using curl and authentication via header: -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects" +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.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. ## Authentication with OAuth2 token -Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter. +Instead of the `private_token` you can transmit the OAuth2 access token as a +header or as a parameter. -### OAuth2 token (as a parameter) +Example of OAuth2 token as a parameter: -``` -curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN +```shell +curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN ``` -### OAuth2 token (as a header) +Example of OAuth2 token as a header: -``` -curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user +```shell +curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/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. - -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 +The API is designed to return different status codes according to context and +action. This way if a request results in an error, the caller is able to get +insight into what went wrong. + +The following table gives an overview of how the API functions generally behave. + +| Request type | Explanation | +| ------------ | ----------- | +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. | +| `DELETE` | Designed to be idempotent, meaning a request to 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 table shows the possible return codes for API requests. + +| Return values | Explanation | +| ------------- | ----------- | +| `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](#authentication) is necessary. | +| `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. | ## 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, +provided your private token is from an administration account. You need to pass +the `sudo` parameter by URL or header with an ID or username of the user you +want to perform the operation as. If passed as a 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: +If a non administrative `private_token` is provided, then an error message will +be returned with status code `403`: ```json { @@ -116,7 +126,8 @@ If a non administrative `private_token` is provided then an error message will b } ``` -If the sudo user id or username cannot be found then an error message will be returned with status code 404: +If the sudo user id or username cannot be found, an error message will be +returned with status code `404`: ```json { @@ -124,94 +135,133 @@ If the sudo user id or username cannot be found then an error message will be re } ``` -Example of a valid API with sudo request: +Example of a valid API call with sudo request providing a username and an ID +respectively: -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username +```shell +GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username ``` -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23 +```shell +GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 ``` -Example for a valid API request with sudo using curl and authentication via header: +Example of 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" +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects" ``` -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects" +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects" ``` ## Pagination -When listing resources you can pass the following parameters: +Sometimes the returned result will span across many lines. 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 +| Parameter | Description | +| --------- | ----------- | +| `page` | Page number (default: `1`). | +| `per_page`| Number of items to list per page (default: `20`, max: `100`). | -[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. +In the example below, we list 50 [namespaces](namespaces.md) per page. + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50 +``` + +[Link headers](http://www.w3.org/wiki/LinkHeader) are sent 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 -When you work with API you may notice two similar fields in api entities: id and iid. The main difference between them is scope. Example: +When you work with the API, you may notice two similar fields in API entities: +`id` and `iid`. The main difference between them is scope. + +For example, an issue might have `id: 46` and `iid: 5`. -Issue: +| Parameter | Description | +| --------- | ----------- | +| id | is unique across all issues and is used for any API call. | +| iid | is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see the `iid`. | - id: 46 - iid: 5 +That means that if you want to get an issue via the API you should use: + +```bash +https://gitlab.example.com/api/v3/projects/42/issues/:id.json +``` -- id - is unique across all issues. It's used for any api call. -- iid - is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see iid. +On the other hand, if you want to create a link to a web page you should use: -So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use `http:://host/project/issues/:iid.json` +```bash +https://gitlab.example.com/api/v3/projects/42/issues/:iid.json +``` ## Data validation and error reporting -When working with the API you may encounter validation errors. In such case, the API will answer with an HTTP `400` status. +When working with the API you may encounter validation errors. In such case, +the API will answer with an HTTP `400` status. + Such errors appear in two cases: -* A required attribute of the API request is missing, e.g. the title of an issue is not given -* An attribute did not pass the validation, e.g. user bio is too long +- A required attribute of the API request is missing, e.g. the title of an + issue is not given +- An attribute did not pass the validation, e.g. user bio is too long When an attribute is missing, you will get something like: - HTTP/1.1 400 Bad Request - Content-Type: application/json - - { - "message":"400 (Bad request) \"title\" not given" - } - -When a validation error occurs, error messages will be different. They will hold all details of validation errors: +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message":"400 (Bad request) \"title\" not given" +} +``` - HTTP/1.1 400 Bad Request - Content-Type: application/json +When a validation error occurs, error messages will be different. They will +hold all details of validation errors: - { - "message": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] } +} +``` -This makes error messages more machine-readable. The format can be described as follow: +This makes error messages more machine-readable. The format can be described as +follows: - { - "message": { +```json +{ + "message": { + "": [ + "", + "", + ... + ], + "": { "": [ "", "", ... ], - "": { - "": [ - "", - "", - ... - ], - } } } +} +``` + +## Clients + +There are many unofficial GitLab API Clients for most of the popular +programming languages. Visit the [GitLab website][] for a complete list. + +[GitLab website]: https://about.gitlab.com/applications/#api-clients -- cgit v1.2.1 From 958dd277775146fb35fc53ae7f6b6c30a96deb50 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 11:38:54 +0100 Subject: Clean-up API README [ci skip] - Fix some curl examples - Fix examples for id vs iid --- doc/api/README.md | 69 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 29 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 0b902b9b2b9..2b6466a9e57 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,7 +1,13 @@ # GitLab API +Automate GitLab via a simple and powerful API. All definitions can be found +under [/lib/api](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). + ## Resources +Documentation for various API resources can be found separately in the +following locations: + - [Users](users.md) - [Session](session.md) - [Projects](projects.md) including setting Webhooks @@ -44,7 +50,7 @@ returned with status code `401`: ``` API requests should be prefixed with `api` and the API version. The API version -is defined in `lib/api.rb`. +is defined in [`lib/api.rb`][lib-api-url]. Example of a valid API request: @@ -52,13 +58,14 @@ Example of a valid API request: GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK ``` -Example of a valid API request using curl and authentication via header: +Example of a valid API request using cURL and authentication via header: ```shell curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.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. +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of an API URL. ## Authentication with OAuth2 token @@ -82,21 +89,21 @@ 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. This way if a request results in an error, the caller is able to get +action. This way, if a request results in an error, the caller is able to get insight into what went wrong. The following table gives an overview of how the API functions generally behave. -| Request type | Explanation | +| Request type | Description | | ------------ | ----------- | | `GET` | Access one or more resources and return the result as JSON. | | `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | | `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. | -| `DELETE` | Designed to be idempotent, meaning a request to 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. | +| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. | The following table shows the possible return codes for API requests. -| Return values | Explanation | +| Return values | Description | | ------------- | ----------- | | `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. | @@ -107,15 +114,15 @@ The following table shows the possible return codes for API requests. | `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. | +| `500 Server Error` | While handling the request something went wrong server-side. | ## Sudo All API requests support performing an API call as if you were another user, -provided your private token is from an administration account. You need to pass -the `sudo` parameter by URL or header with an ID or username of the user you -want to perform the operation as. If passed as a header, the header name must -be **SUDO** (capitals). +provided your private token is from an administrator account. You need to pass +the `sudo` parameter either by URL or a header with an ID/username of the user +you want to perform the operation as. If passed as a 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`: @@ -135,22 +142,24 @@ returned with status code `404`: } ``` -Example of a valid API call with sudo request providing a username and an ID -respectively: +--- + +Example of a valid API call and a request using cURL with sudo request, +providing a username: ```shell GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username ``` ```shell -GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects" ``` -Example of a valid API request with sudo using curl and authentication via -header: +Example of a valid API call and a request using cURL with sudo request, +providing an ID: ```shell -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects" +GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 ``` ```shell @@ -164,8 +173,8 @@ resources you can pass the following parameters. | Parameter | Description | | --------- | ----------- | -| `page` | Page number (default: `1`). | -| `per_page`| Number of items to list per page (default: `20`, max: `100`). | +| `page` | Page number (default: `1`) | +| `per_page`| Number of items to list per page (default: `20`, max: `100`) | In the example below, we list 50 [namespaces](namespaces.md) per page. @@ -230,19 +239,20 @@ For example, an issue might have `id: 46` and `iid: 5`. | Parameter | Description | | --------- | ----------- | -| id | is unique across all issues and is used for any API call. | -| iid | is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see the `iid`. | +| `id` | Is unique across all issues and is used for any API call | +| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` | -That means that if you want to get an issue via the API you should use: +That means that if you want to get an issue via the API you should use the `id`: ```bash -https://gitlab.example.com/api/v3/projects/42/issues/:id.json +GET /projects/42/issues/:id ``` -On the other hand, if you want to create a link to a web page you should use: +On the other hand, if you want to create a link to a web page you should use +the `iid`: ```bash -https://gitlab.example.com/api/v3/projects/42/issues/:iid.json +GET /projects/42/issues/:iid ``` ## Data validation and error reporting @@ -258,7 +268,7 @@ Such errors appear in two cases: When an attribute is missing, you will get something like: -``` +```json HTTP/1.1 400 Bad Request Content-Type: application/json { @@ -269,7 +279,7 @@ Content-Type: application/json When a validation error occurs, error messages will be different. They will hold all details of validation errors: -``` +```json HTTP/1.1 400 Bad Request Content-Type: application/json { @@ -308,4 +318,5 @@ follows: There are many unofficial GitLab API Clients for most of the popular programming languages. Visit the [GitLab website][] for a complete list. -[GitLab website]: https://about.gitlab.com/applications/#api-clients +[GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API" +[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb -- cgit v1.2.1 From 2ffc438efb81e2bbfe83c68860345e5902339bac Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 11:45:04 +0100 Subject: Use plaintext instead of json in code blocks [ci skip] --- doc/api/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 2b6466a9e57..a9bfd2f7ebc 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -268,7 +268,7 @@ Such errors appear in two cases: When an attribute is missing, you will get something like: -```json +``` HTTP/1.1 400 Bad Request Content-Type: application/json { @@ -279,7 +279,7 @@ Content-Type: application/json When a validation error occurs, error messages will be different. They will hold all details of validation errors: -```json +``` HTTP/1.1 400 Bad Request Content-Type: application/json { -- cgit v1.2.1 From 84354b4bd28eff817f068e48bd64faf882952e96 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 21:49:04 +0100 Subject: Fix typos, grammar and other styleguide issues [ci skip] --- doc/api/README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index a9bfd2f7ebc..9f3ad126320 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,7 +1,7 @@ # GitLab API Automate GitLab via a simple and powerful API. All definitions can be found -under [/lib/api](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). +under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). ## Resources @@ -36,9 +36,9 @@ following locations: ## Authentication All API requests require authentication. You need to pass a `private_token` -parameter by URL or header. If passed as a 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 account page (`/profile/account`). +parameter via query string or header. If passed as a header, the header name +must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore). +You can find or reset your private token in your account page (`/profile/account`). If `private_token` is invalid or omitted, then an error message will be returned with status code `401`: @@ -107,12 +107,12 @@ The following table shows the possible return codes for API requests. | ------------- | ----------- | | `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. | +| `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](#authentication) is necessary. | -| `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. | +| `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. | +| `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 server-side. | @@ -120,9 +120,9 @@ The following table shows the possible return codes for API requests. All API requests support performing an API call as if you were another user, provided your private token is from an administrator account. You need to pass -the `sudo` parameter either by URL or a header with an ID/username of the user -you want to perform the operation as. If passed as a header, the header name -must be **SUDO** (capitals). +the `sudo` parameter either via query string or a header with an ID/username of +the user you want to perform the operation as. If passed as a header, the +header name must be `SUDO` (uppercase). If a non administrative `private_token` is provided, then an error message will be returned with status code `403`: @@ -133,7 +133,7 @@ be returned with status code `403`: } ``` -If the sudo user id or username cannot be found, an error message will be +If the sudo user ID or username cannot be found, an error message will be returned with status code `404`: ```json @@ -168,8 +168,8 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https:/ ## Pagination -Sometimes the returned result will span across many lines. When listing -resources you can pass the following parameters. +Sometimes the returned result will span across many pages. When listing +resources you can pass the following parameters: | Parameter | Description | | --------- | ----------- | @@ -230,7 +230,7 @@ Additional pagination headers are also sent back. | `X-Next-Page` | The index of the next page | | `X-Prev-Page` | The index of the previous page | -## id vs iid +## `id` vs `iid` When you work with the API, you may notice two similar fields in API entities: `id` and `iid`. The main difference between them is scope. @@ -257,14 +257,14 @@ GET /projects/42/issues/:iid ## Data validation and error reporting -When working with the API you may encounter validation errors. In such case, +When working with the API you may encounter validation errors, in which case the API will answer with an HTTP `400` status. Such errors appear in two cases: -- A required attribute of the API request is missing, e.g. the title of an +- A required attribute of the API request is missing, e.g., the title of an issue is not given -- An attribute did not pass the validation, e.g. user bio is too long +- An attribute did not pass the validation, e.g., user bio is too long When an attribute is missing, you will get something like: @@ -316,7 +316,7 @@ follows: ## Clients There are many unofficial GitLab API Clients for most of the popular -programming languages. Visit the [GitLab website][] for a complete list. +programming languages. Visit the [GitLab website] for a complete list. [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API" [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb -- cgit v1.2.1 From 1ede975cde6d32a74b2d4d523e5c0e242c89d50d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 19 Jan 2016 11:18:17 +0100 Subject: Styleguide the commit status API [ci skip] --- doc/api/commits.md | 202 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 127 insertions(+), 75 deletions(-) (limited to 'doc/api') diff --git a/doc/api/commits.md b/doc/api/commits.md index a07c9dff54e..4008629e0a2 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -158,8 +158,21 @@ Example response: ## Post comment to commit -Adds a comment to a commit. Optionally you can post comments on a specific line -of a commit. In that case `path`, `line` and `line_type` 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 @@ -168,35 +181,33 @@ POST /projects/:id/repository/commits/:sha/comments | 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 | -| `note` | string | yes | Text of comment | +| `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 | +| `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 | -In order to post a comment in a particular line of a particular file, you must -specify `path`, `line` and `line_type` should be `new`. - ```bash -curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments?note=New%20comment&path=CHANGELOG&line=664&line_type=new" +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 ``` 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!" } ``` @@ -208,75 +219,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 -- `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 +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses +``` + +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" } ``` -- cgit v1.2.1 From 373b277f033e12fd9a3a1e12367dd5cf120f3586 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 22 Jan 2016 10:08:57 +0100 Subject: Add note about commit status API deprecation [ci skip] --- doc/api/commits.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/commits.md b/doc/api/commits.md index 4008629e0a2..e4d436b8e52 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -211,7 +211,12 @@ Example response: } ``` -## 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. @@ -285,7 +290,7 @@ Example response: ] ``` -## Post the build status to a commit +### Post the build status to a commit Adds or updates a build status of a commit. -- cgit v1.2.1 From 2b3e64a6015bcb9a2bf365dcab148d5024833d91 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sun, 24 Jan 2016 19:28:24 +0100 Subject: Clean up namespaces API documentation [ci skip] --- doc/api/namespaces.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'doc/api') diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 68ed8bd3152..42d9ce3d391 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,22 +1,29 @@ # Namespaces -Namespaces account for usernames and groupnames. +Usernames and groupnames fall under a special category called namespaces. + +For users and groups supported API calls see the [users](users.md) and +[groups](groups.md) documentation respectively. [Pagination](README.md#pagination) is used. ## List namespaces -Get a list of namespaces. As a user, your namespaces are listed whereas if you -are an administrator you get a list of all namespaces in the GitLab instance. +Get a list of the namespaces of the authenticated user. If the user is an +administrator, a list of all namespaces in the GitLab instance is shown. ``` GET /namespaces ``` +Example request: + ```bash curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces ``` +Example response: + ```json [ { @@ -44,10 +51,14 @@ GET /namespaces?search=foobar | --------- | ---- | -------- | ----------- | | `search` | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria | +Example request: + ```bash curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter ``` +Example response: + ```json [ { -- cgit v1.2.1 From 23a878c40ca8ca73d371c561bb4d2730551f3a38 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sun, 24 Jan 2016 20:19:46 +0100 Subject: Clean up system hooks API documentation [ci skip] --- doc/api/system_hooks.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) (limited to 'doc/api') diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index b605f3540f3..dc036d7e27f 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,18 +1,24 @@ # System hooks -All methods require admin authorization. +All methods require administrator authorization. The URL endpoint of the system hooks can also be configured using the UI in -the admin area under hooks(`/admin/hooks`). +the admin area under **Hooks** (`/admin/hooks`). + +Read more about [system hooks](../system_hooks/system_hooks.md). ## List system hooks Get a list of all system hooks. +--- + ``` GET /hooks ``` +Example request: + ```bash curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks ``` @@ -31,6 +37,10 @@ Example response: ## Add new system hook +Add a new system hook. + +--- + ``` POST /hooks ``` @@ -39,6 +49,8 @@ POST /hooks | --------- | ---- | -------- | ----------- | | `url` | string | yes | The hook URL | +Example request: + ```bash curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook" ``` @@ -65,6 +77,8 @@ GET /hooks/:id | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the hook | +Example request: + ```bash curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 ``` @@ -85,8 +99,12 @@ Example response: ## 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 a JSON object is -returned. +even if the hook is not available. + +If the hook is deleted, a JSON object is returned. An error is raised if the +hook is not found. + +--- ``` DELETE /hooks/:id @@ -96,6 +114,8 @@ DELETE /hooks/:id | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the hook | +Example request: + ```bash curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 ``` -- cgit v1.2.1 From a8fc4a01e26ab6be088ce6c1179770c757d805e1 Mon Sep 17 00:00:00 2001 From: Markus Fisch Date: Wed, 27 Jan 2016 12:16:37 +0000 Subject: Fixed typo for PRIVATE-TOKEN header Was PRIVATE_TOKEN but should be PRIVATE-TOKEN. Underscore vs. kebab-case. --- doc/api/builds.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/api') diff --git a/doc/api/builds.md b/doc/api/builds.md index ecb50754c88..6e64d096644 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -18,7 +18,7 @@ GET /projects/:id/builds ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds" ``` ### Example of response @@ -123,7 +123,7 @@ GET /projects/:id/repository/commits/:sha/builds ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds" ``` ### Example of response @@ -213,7 +213,7 @@ GET /projects/:id/builds/:build_id ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8" ``` ### Example of response @@ -277,7 +277,7 @@ POST /projects/:id/builds/:build_id/cancel ### Example of request ``` -curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel" ``` ### Example of response @@ -327,7 +327,7 @@ POST /projects/:id/builds/:build_id/retry ### Example of request ``` -curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry" ``` ### Example of response -- cgit v1.2.1 From dfb8803c1cf5946d3eb7d0e70ba6fa8896f67a6f Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Thu, 28 Jan 2016 14:26:02 +0100 Subject: Improve consistency and duplication for Merge Request API * Follow REST for merge request API route * Remove repeating comments API for MR Signed-off-by: Dmitriy Zaporozhets --- doc/api/merge_requests.md | 74 +++++------------------------------------------ 1 file changed, 7 insertions(+), 67 deletions(-) (limited to 'doc/api') diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 8bc0a67067a..85ed31320b9 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -60,7 +60,7 @@ Parameters: Shows information about a single merge request. ``` -GET /projects/:id/merge_request/:merge_request_id +GET /projects/:id/merge_requests/:merge_request_id ``` Parameters: @@ -105,7 +105,7 @@ Parameters: Get a list of merge request commits. ``` -GET /projects/:id/merge_request/:merge_request_id/commits +GET /projects/:id/merge_requests/:merge_request_id/commits ``` Parameters: @@ -142,7 +142,7 @@ Parameters: Shows information about the merge request including its files and changes. ``` -GET /projects/:id/merge_request/:merge_request_id/changes +GET /projects/:id/merge_requests/:merge_request_id/changes ``` Parameters: @@ -264,7 +264,7 @@ If an error occurs, an error number and a message explaining the reason is retur Updates an existing merge request. You can change the target branch, title, or even close the MR. ``` -PUT /projects/:id/merge_request/:merge_request_id +PUT /projects/:id/merge_requests/:merge_request_id ``` Parameters: @@ -323,7 +323,7 @@ If merge request is already merged or closed - you get 405 and error message 'Me If you don't have permissions to accept this merge request - you'll get a 401 ``` -PUT /projects/:id/merge_request/:merge_request_id/merge +PUT /projects/:id/merge_requests/:merge_request_id/merge ``` Parameters: @@ -373,7 +373,7 @@ If the merge request is already merged or closed - you get 405 and error message In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error. ``` -PUT /projects/:id/merge_request/:merge_request_id/cancel_merge_when_build_succeeds +PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_build_succeeds ``` Parameters: @@ -409,66 +409,6 @@ Parameters: } ``` -## Post comment to MR - -Adds a comment to a merge request. - -``` -POST /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request -- `note` (required) - Text of comment - -```json -{ - "note": "text1" -} -``` - -## Get the comments on a MR - -Gets all the comments associated with a merge request. - -``` -GET /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request - -```json -[ - { - "note": "this is the 1st comment on the 2merge merge request", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - }, - { - "note": "Status changed to closed", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - } -] -``` - ## Comments on merge requets -Comments are done via the notes resource. +Comments are done via the [notes](notes.md) resource. -- cgit v1.2.1