summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md1
-rw-r--r--doc/api/groups.md70
-rw-r--r--doc/api/merge_requests.md125
-rw-r--r--doc/api/notes.md22
-rw-r--r--doc/api/projects.md93
-rw-r--r--doc/api/settings.md2
-rw-r--r--doc/api/tags.md39
7 files changed, 318 insertions, 34 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 6b8528de50c..25a31b235cc 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -10,6 +10,7 @@
- [Repositories](repositories.md)
- [Repository Files](repository_files.md)
- [Commits](commits.md)
+- [Tags](tags.md)
- [Branches](branches.md)
- [Merge Requests](merge_requests.md)
- [Issues](issues.md)
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 0b9f6406d8d..808675d8605 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -1,6 +1,6 @@
# Groups
-## List project groups
+## List groups
Get a list of groups. (As user: my groups, as admin: all groups)
@@ -21,6 +21,70 @@ GET /groups
You can search for groups by name or path, see below.
+
+## List a group's projects
+
+Get a list of projects in this group.
+
+```
+GET /groups/:id/projects
+```
+
+Parameters:
+
+- `archived` (optional) - if passed, limit by archived status
+- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
+- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+- `search` (optional) - Return list of authorized projects according to a search criteria
+- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first
+
+```json
+[
+ {
+ "id": 4,
+ "description": null,
+ "default_branch": "master",
+ "public": false,
+ "visibility_level": 0,
+ "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
+ "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
+ "web_url": "http://example.com/diaspora/diaspora-client",
+ "tag_list": [
+ "example",
+ "disapora client"
+ ],
+ "owner": {
+ "id": 3,
+ "name": "Diaspora",
+ "created_at": "2013-09-30T13: 46: 02Z"
+ },
+ "name": "Diaspora Client",
+ "name_with_namespace": "Diaspora / Diaspora Client",
+ "path": "diaspora-client",
+ "path_with_namespace": "diaspora/diaspora-client",
+ "issues_enabled": true,
+ "merge_requests_enabled": true,
+ "builds_enabled": true,
+ "wiki_enabled": true,
+ "snippets_enabled": false,
+ "created_at": "2013-09-30T13: 46: 02Z",
+ "last_activity_at": "2013-09-30T13: 46: 02Z",
+ "creator_id": 3,
+ "namespace": {
+ "created_at": "2013-09-30T13: 46: 02Z",
+ "description": "",
+ "id": 3,
+ "name": "Diaspora",
+ "owner_id": 1,
+ "path": "diaspora",
+ "updated_at": "2013-09-30T13: 46: 02Z"
+ },
+ "archived": false,
+ "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png"
+ }
+]
+```
+
## Details of a group
Get all details of a group.
@@ -186,7 +250,7 @@ To get more (up to 100), pass the following as an argument to the API call:
/groups?per_page=100
```
-And to switch pages add:
+And to switch pages add:
```
/groups?per_page=100&page=2
-``` \ No newline at end of file
+```
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 2f17d4ae06b..366a1f8abec 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -3,8 +3,9 @@
## List merge requests
Get all merge requests for this project.
-The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`).
-The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
+The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`).
+The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. With GitLab 8.2 the return fields `upvotes` and
+`downvotes` are deprecated and always return `0`.
```
GET /projects/:id/merge_requests
@@ -31,6 +32,8 @@ Parameters:
"project_id": 3,
"title": "test1",
"state": "opened",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"id": 1,
"username": "admin",
@@ -55,7 +58,7 @@ Parameters:
## Get single MR
-Shows information about a single merge request.
+Shows information about a single merge request. With GitLab 8.2 the return fields `upvotes` and `downvotes` are deprecated and always return `0`.
```
GET /projects/:id/merge_request/:merge_request_id
@@ -75,6 +78,8 @@ Parameters:
"project_id": 3,
"title": "test1",
"state": "merged",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"id": 1,
"username": "admin",
@@ -96,9 +101,48 @@ Parameters:
}
```
+## Get single MR commits
+
+Get a list of merge request commits.
+
+```
+GET /projects/:id/merge_request/:merge_request_id/commits
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - The ID of MR
+
+
+```json
+[
+ {
+ "id": "ed899a2f4b50b4370feeea94676502b42383c746",
+ "short_id": "ed899a2f4b5",
+ "title": "Replace sanitize with escape once",
+ "author_name": "Dmitriy Zaporozhets",
+ "author_email": "dzaporozhets@sphereconsultinginc.com",
+ "created_at": "2012-09-20T11:50:22+03:00",
+ "message": "Replace sanitize with escape once"
+ },
+ {
+ "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
+ "short_id": "6104942438c",
+ "title": "Sanitize for network graph",
+ "author_name": "randx",
+ "author_email": "dmitriy.zaporozhets@gmail.com",
+ "created_at": "2012-09-20T09:06:12+03:00",
+ "message": "Sanitize for network graph"
+ }
+]
+```
+
## Get single MR changes
-Shows information about the merge request including its files and changes
+Shows information about the merge request including its files and changes.
+With GitLab 8.2 the return fields `upvotes` and `downvotes` are deprecated and
+always return `0`.
```
GET /projects/:id/merge_request/:merge_request_id/changes
@@ -122,6 +166,8 @@ Parameters:
"updated_at": "2015-02-02T20:08:49.959Z",
"target_branch": "secret_token",
"source_branch": "version-1-9",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"name": "Chad Hamill",
"username": "jarrett",
@@ -150,7 +196,7 @@ Parameters:
"updated_at": "2015-02-02T19:49:26.013Z",
"due_date": null
},
- "files": [
+ "changes": [
{
"old_path": "VERSION",
"new_path": "VERSION",
@@ -167,7 +213,8 @@ Parameters:
## Create MR
-Creates a new merge request.
+Creates a new merge request. With GitLab 8.2 the return fields `upvotes` and `
+downvotes` are deprecated and always return `0`.
```
POST /projects/:id/merge_requests
@@ -192,6 +239,8 @@ Parameters:
"project_id": 3,
"title": "test1",
"state": "opened",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"id": 1,
"username": "admin",
@@ -217,7 +266,8 @@ If an error occurs, an error number and a message explaining the reason is retur
## Update MR
-Updates an existing merge request. You can change the target branch, title, or even close the MR.
+Updates an existing merge request. You can change the target branch, title, or even close the MR. With GitLab 8.2 the return fields `upvotes` and `downvotes`
+are deprecated and always return `0`.
```
PUT /projects/:id/merge_request/:merge_request_id
@@ -242,6 +292,8 @@ Parameters:
"title": "test1",
"description": "description1",
"state": "opened",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"id": 1,
"username": "admin",
@@ -266,7 +318,8 @@ If an error occurs, an error number and a message explaining the reason is retur
## Accept MR
-Merge changes submitted with MR using this API.
+Merge changes submitted with MR using this API. With GitLab 8.2 the return
+fields `upvotes` and `downvotes` are deprecated and always return `0`.
If merge success you get `200 OK`.
@@ -282,9 +335,57 @@ PUT /projects/:id/merge_request/:merge_request_id/merge
Parameters:
-- `id` (required) - The ID of a project
-- `merge_request_id` (required) - ID of MR
-- `merge_commit_message` (optional) - Custom merge commit message
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - ID of MR
+- `merge_commit_message` (optional) - Custom merge commit message
+- `should_remove_source_branch` (optional) - if `true` removes the source branch
+- `merged_when_build_succeeds` (optional) - if `true` the MR is merge when the build succeeds
+
+```json
+{
+ "id": 1,
+ "target_branch": "master",
+ "source_branch": "test1",
+ "project_id": 3,
+ "title": "test1",
+ "state": "merged",
+ "upvotes": 0,
+ "downvotes": 0,
+ "author": {
+ "id": 1,
+ "username": "admin",
+ "email": "admin@example.com",
+ "name": "Administrator",
+ "state": "active",
+ "created_at": "2012-04-29T08:46:00Z"
+ },
+ "assignee": {
+ "id": 1,
+ "username": "admin",
+ "email": "admin@example.com",
+ "name": "Administrator",
+ "state": "active",
+ "created_at": "2012-04-29T08:46:00Z"
+ }
+}
+```
+
+## Cancel Merge When Build Succeeds
+
+If successful you'll get `200 OK`.
+
+If you don't have permissions to accept this merge request - you'll get a 401
+
+If the merge request is already merged or closed - you get 405 and error message 'Method Not Allowed'
+
+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
+```
+Parameters:
+
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - ID of MR
```json
{
@@ -294,6 +395,8 @@ Parameters:
"project_id": 3,
"title": "test1",
"state": "merged",
+ "upvotes": 0,
+ "downvotes": 0,
"author": {
"id": 1,
"username": "admin",
diff --git a/doc/api/notes.md b/doc/api/notes.md
index bcba1f62151..4d7ef288df8 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -6,7 +6,8 @@ Notes are comments on snippets, issues or merge requests.
### List project issue notes
-Gets a list of all notes for a single issue.
+Gets a list of all notes for a single issue. With GitLab 8.2 the return fields
+`upvote` and `downvote` are deprecated and always return `false`.
```
GET /projects/:id/issues/:issue_id/notes
@@ -32,7 +33,11 @@ Parameters:
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
- "system": true
+ "system": true,
+ "upvote": false,
+ "downvote": false,
+ "noteable_id": 377,
+ "noteable_type": "Issue"
},
{
"id": 305,
@@ -47,7 +52,11 @@ Parameters:
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
- "system": false
+ "system": true,
+ "upvote": false,
+ "downvote": false,
+ "noteable_id": 121,
+ "noteable_type": "Issue"
}
]
```
@@ -214,7 +223,12 @@ Parameters:
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
- "created_at": "2013-10-02T08:57:14Z"
+ "created_at": "2013-10-02T08:57:14Z",
+ "system": false,
+ "upvote": false,
+ "downvote": false,
+ "noteable_id": 2,
+ "noteable_type": "MergeRequest"
}
```
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 755cc6525c2..658e65c6f01 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -32,7 +32,6 @@ Parameters:
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
-- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first
```json
[
@@ -59,6 +58,7 @@ Parameters:
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"issues_enabled": true,
+ "open_issues_count": 1,
"merge_requests_enabled": true,
"builds_enabled": true,
"wiki_enabled": true,
@@ -101,6 +101,7 @@ Parameters:
"path": "puppet",
"path_with_namespace": "brightbox/puppet",
"issues_enabled": true,
+ "open_issues_count": 1,
"merge_requests_enabled": true,
"builds_enabled": true,
"wiki_enabled": true,
@@ -137,7 +138,21 @@ Parameters:
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
-- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first
+
+### List starred projects
+
+Get a list of projects which are starred by the authenticated user.
+
+```
+GET /projects/starred
+```
+
+Parameters:
+
+- `archived` (optional) - if passed, limit by archived status
+- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
+- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+- `search` (optional) - Return list of authorized projects according to a search criteria
### List ALL projects
@@ -153,7 +168,6 @@ Parameters:
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
-- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first
### Get single project
@@ -192,6 +206,7 @@ Parameters:
"path": "diaspora-project-site",
"path_with_namespace": "diaspora/diaspora-project-site",
"issues_enabled": true,
+ "open_issues_count": 1,
"merge_requests_enabled": true,
"builds_enabled": true,
"wiki_enabled": true,
@@ -245,9 +260,17 @@ Parameters:
"target_id": 830,
"target_type": "Issue",
"author_id": 1,
- "author_username": "john",
"data": null,
- "target_title": "Public project search field"
+ "target_title": "Public project search field",
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "username": "root",
+ "id": 1,
+ "state": "active",
+ "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
+ "web_url": "http://localhost:3000/u/root"
+ },
+ "author_username": "root"
},
{
"title": null,
@@ -256,6 +279,14 @@ Parameters:
"target_id": null,
"target_type": null,
"author_id": 1,
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "username": "root",
+ "id": 1,
+ "state": "active",
+ "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
+ "web_url": "http://localhost:3000/u/root"
+ },
"author_username": "john",
"data": {
"before": "50d4420237a9de7be1304607147aec22e4a14af7",
@@ -292,9 +323,56 @@ Parameters:
"target_id": 840,
"target_type": "Issue",
"author_id": 1,
- "author_username": "john",
"data": null,
- "target_title": "Finish & merge Code search PR"
+ "target_title": "Finish & merge Code search PR",
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "username": "root",
+ "id": 1,
+ "state": "active",
+ "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
+ "web_url": "http://localhost:3000/u/root"
+ },
+ "author_username": "root"
+ },
+ {
+ "title": null,
+ "project_id": 15,
+ "action_name": "commented on",
+ "target_id": 1312,
+ "target_type": "Note",
+ "author_id": 1,
+ "data": null,
+ "target_title": null,
+ "created_at": "2015-12-04T10:33:58.089Z",
+ "note": {
+ "id": 1312,
+ "body": "What an awesome day!",
+ "attachment": null,
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "username": "root",
+ "id": 1,
+ "state": "active",
+ "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
+ "web_url": "http://localhost:3000/u/root"
+ },
+ "created_at": "2015-12-04T10:33:56.698Z",
+ "system": false,
+ "upvote": false,
+ "downvote": false,
+ "noteable_id": 377,
+ "noteable_type": "Issue"
+ },
+ "author": {
+ "name": "Dmitriy Zaporozhets",
+ "username": "root",
+ "id": 1,
+ "state": "active",
+ "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
+ "web_url": "http://localhost:3000/u/root"
+ },
+ "author_username": "root"
}
]
```
@@ -335,7 +413,6 @@ Parameters:
- `user_id` (required) - user_id of owner
- `name` (required) - new project name
- `description` (optional) - short project description
-- `default_branch` (optional) - 'master' by default
- `issues_enabled` (optional)
- `merge_requests_enabled` (optional)
- `builds_enabled` (optional)
diff --git a/doc/api/settings.md b/doc/api/settings.md
index d1b93a09c02..96867c67915 100644
--- a/doc/api/settings.md
+++ b/doc/api/settings.md
@@ -57,7 +57,7 @@ Parameters:
- `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 applicaitons
+- `user_oauth_applications` - allow users to create oauth applications
- `after_sign_out_path` - where redirect user after logout
All parameters are optional. You can send only one that you want to change.
diff --git a/doc/api/tags.md b/doc/api/tags.md
index b5b90cf6b82..085d387e824 100644
--- a/doc/api/tags.md
+++ b/doc/api/tags.md
@@ -29,7 +29,7 @@ Parameters:
]
},
"release": {
- "tag": "1.0.0",
+ "tag_name": "1.0.0",
"description": "Amazing release. Wow"
},
"name": "v1.0.0",
@@ -70,7 +70,7 @@ Parameters:
]
},
"release": {
- "tag": "1.0.0",
+ "tag_name": "1.0.0",
"description": "Amazing release. Wow"
},
"name": "v1.0.0",
@@ -84,23 +84,48 @@ It returns 200 if the operation succeed. In case of an error,
405 with an explaining error message is returned.
-## New release
+## Create a new release
-Add release notes to the existing git tag
+Add release notes to the existing git tag. It returns 201 if the release is
+created successfully. If the tag does not exist, 404 is returned. If there
+already exists a release for the given tag, 409 is returned.
```
-PUT /projects/:id/repository/:tag/release
+POST /projects/:id/repository/tags/:tag_name/release
```
Parameters:
- `id` (required) - The ID of a project
-- `tag` (required) - The name of a tag
+- `tag_name` (required) - The name of a tag
- `description` (required) - Release notes with markdown support
```json
{
- "tag": "1.0.0",
+ "tag_name": "1.0.0",
"description": "Amazing release. Wow"
}
```
+
+## Update a release
+
+Updates the release notes of a given release. It returns 200 if the release is
+successfully updated. If the tag or the release does not exist, it returns 404
+with a proper error message.
+
+```
+PUT /projects/:id/repository/tags/:tag_name/release
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `tag_name` (required) - The name of a tag
+- `description` (required) - Release notes with markdown support
+
+```json
+{
+ "tag_name": "1.0.0",
+ "description": "Amazing release. Wow"
+}
+``` \ No newline at end of file
View Lorry Controller Status