From 01a1e3925acf01b925ad3b8ca370db30384111d8 Mon Sep 17 00:00:00 2001 From: Miroslav Meca Date: Thu, 25 Aug 2016 12:01:52 +0000 Subject: Update projects.md The wrong example for "Branches". Added option parameters in protect branch section. Here is reason: https://gitlab.com/gitlab-org/gitlab-ee/commit/3ab07b8aae8dae43cfa3aae1306c59ea264a8594 Maybe this section could/should be deleted. Because in file repositories.md it had been deleted: https://gitlab.com/gitlab-org/gitlab-ee/commit/8f3701eff005aeedcebff8ce02074f5056a369b3 --- doc/api/projects.md | 54 ++++++++++++++++++++++++----------------------------- 1 file changed, 24 insertions(+), 30 deletions(-) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 0e4806e31c5..eacdb1e1ee6 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -998,6 +998,8 @@ is available before it is returned in the JSON response or an empty response is ## Branches +For more information please consult the [Branches](branches.md) documentation. + ### List branches Lists all branches of a project. @@ -1016,56 +1018,46 @@ Parameters: "name": "async", "commit": { "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca", - "parents": [ - { - "id": "3f94fc7c85061973edc9906ae170cc269b07ca55" - } + "parent_ids": [ + "3f94fc7c85061973edc9906ae170cc269b07ca55" ], - "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee", "message": "give Caolan credit where it's due (up top)", - "author": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "committer": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, + "author_name": "Jeremy Ashkenas", + "author_email": "jashkenas@example.com", "authored_date": "2010-12-08T21:28:50+00:00", + "committer_name": "Jeremy Ashkenas", + "committer_email": "jashkenas@example.com", "committed_date": "2010-12-08T21:28:50+00:00" }, - "protected": false + "protected": false, + "developers_can_push": false, + "developers_can_merge": false }, { "name": "gh-pages", "commit": { "id": "101c10a60019fe870d21868835f65c25d64968fc", - "parents": [ - { - "id": "9c15d2e26945a665131af5d7b6d30a06ba338aaa" - } + "parent_ids": [ + "9c15d2e26945a665131af5d7b6d30a06ba338aaa" ], - "tree": "fb5cc9d45da3014b17a876ad539976a0fb9b352a", "message": "Underscore.js 1.5.2", - "author": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "committer": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, + "author_name": "Jeremy Ashkenas", + "author_email": "jashkenas@example.com", "authored_date": "2013-09-07T12:58:21+00:00", + "committer_name": "Jeremy Ashkenas", + "committer_email": "jashkenas@example.com", "committed_date": "2013-09-07T12:58:21+00:00" }, - "protected": false + "protected": false, + "developers_can_push": false, + "developers_can_merge": false } ] ``` -### List single branch +### Single branch -Lists a specific branch of a project. +A specific branch of a project. ``` GET /projects/:id/repository/branches/:branch @@ -1075,6 +1067,8 @@ Parameters: - `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - `branch` (required) - The name of the branch. +- `developers_can_push` - Flag if developers can push to the branch. +- `developers_can_merge` - Flag if developers can merge to the branch. ### Protect single branch -- cgit v1.2.1 From 8c101f9f860e03be20a90cafdcd19f897e47f62d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 30 Aug 2016 13:43:09 +0200 Subject: Mention that the `:id` of a project can also be `NAMESPACE/PROJECT_NAME` [ci skip] --- doc/api/commits.md | 14 +++++++------- doc/api/projects.md | 22 +++++++++++----------- 2 files changed, 18 insertions(+), 18 deletions(-) (limited to 'doc/api') diff --git a/doc/api/commits.md b/doc/api/commits.md index 5c98c5d7565..55d0de7afd9 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,7 +10,7 @@ GET /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch | | `since` | string | no | Only commits after or in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `until` | string | no | Only commits before or in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | @@ -58,7 +58,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -102,7 +102,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -138,7 +138,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -187,7 +187,7 @@ POST /projects/:id/repository/commits/:sha/comments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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 | @@ -232,7 +232,7 @@ GET /projects/:id/repository/commits/:sha/statuses | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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` @@ -306,7 +306,7 @@ POST /projects/:id/statuses/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project +| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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 diff --git a/doc/api/projects.md b/doc/api/projects.md index 0e4806e31c5..22c3d416107 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -489,7 +489,7 @@ PUT /projects/:id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - `name` (optional) - project name - `path` (optional) - repository name for project - `description` (optional) - short project description @@ -519,7 +519,7 @@ POST /projects/fork/:id Parameters: -- `id` (required) - The ID of the project to be forked +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked ### Star a project @@ -532,7 +532,7 @@ POST /projects/:id/star | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -599,7 +599,7 @@ DELETE /projects/:id/star | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -670,7 +670,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" @@ -757,7 +757,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" @@ -839,7 +839,7 @@ DELETE /projects/:id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked ## Uploads @@ -853,7 +853,7 @@ POST /projects/:id/uploads Parameters: -- `id` (required) - The ID of the project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked - `file` (required) - The file to be uploaded ```json @@ -882,7 +882,7 @@ POST /projects/:id/share Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked - `group_id` (required) - The ID of a group - `group_access` (required) - Level of permissions for sharing @@ -1114,7 +1114,7 @@ POST /projects/:id/fork/:forked_from_id Parameters: -- `id` (required) - The ID of the project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked - `forked_from_id:` (required) - The ID of the project that was forked from ### Delete an existing forked from relationship @@ -1125,7 +1125,7 @@ DELETE /projects/:id/fork Parameter: -- `id` (required) - The ID of the project +- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked ## Search for projects by name -- cgit v1.2.1 From 0227e98d0db2eb7fc6a35ddfcd3a0581ab550948 Mon Sep 17 00:00:00 2001 From: Patricio Cano Date: Wed, 24 Aug 2016 17:36:58 -0500 Subject: Added CHANGELOG, documentation, and API functionality --- doc/api/projects.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 3136c493b48..671b4ba7a7a 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -452,6 +452,7 @@ Parameters: - `import_url` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) +- `enable_lfs` (optional) ### Create project for user @@ -478,6 +479,7 @@ Parameters: - `import_url` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) +- `enable_lfs` (optional) ### Edit project @@ -505,6 +507,7 @@ Parameters: - `visibility_level` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) +- `enable_lfs` (optional) On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. -- cgit v1.2.1 From cf37d623e197dae5cc7efb021c1b1d85ca9674ee Mon Sep 17 00:00:00 2001 From: Patricio Cano Date: Tue, 30 Aug 2016 17:17:45 -0500 Subject: Renamed `enable_lfs` to `lfs_enabled` for the Project field, and related fixes. --- doc/api/projects.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 671b4ba7a7a..0d5aa61aa74 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -452,7 +452,7 @@ Parameters: - `import_url` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) -- `enable_lfs` (optional) +- `lfs_enabled` (optional) ### Create project for user @@ -479,7 +479,7 @@ Parameters: - `import_url` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) -- `enable_lfs` (optional) +- `lfs_enabled` (optional) ### Edit project @@ -507,7 +507,7 @@ Parameters: - `visibility_level` (optional) - `public_builds` (optional) - `only_allow_merge_if_build_succeeds` (optional) -- `enable_lfs` (optional) +- `lfs_enabled` (optional) On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. -- cgit v1.2.1 From 727dff3f158b9ef852b2b014d4efe0abd69a23d0 Mon Sep 17 00:00:00 2001 From: Timothy Andrew Date: Fri, 26 Aug 2016 09:37:57 +0530 Subject: Don't expose a user's private token in the `/api/v3/user` API. - This would allow anyone with a personal access token (even a read-only token, once scopes are implemented) to escalate their access by obtaining the private token. --- doc/api/users.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/users.md b/doc/api/users.md index 7e848586dbd..54f7a2a2ace 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -310,8 +310,7 @@ GET /user "can_create_group": true, "can_create_project": true, "two_factor_enabled": true, - "external": false, - "private_token": "dd34asd13as" + "external": false } ``` -- cgit v1.2.1 From 036cc8c27e8340a3eed63444bd3f42f86037f350 Mon Sep 17 00:00:00 2001 From: Robert Schilling Date: Fri, 15 Jul 2016 16:21:53 +0200 Subject: API: Expose issue#confidential --- doc/api/issues.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index b194799ccbf..eed0d2fce51 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -80,7 +80,8 @@ Example response: "subscribed" : false, "user_notes_count": 1, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/6" + "web_url": "http://example.com/example/example/issues/6", + "confidential": false } ] ``` @@ -158,7 +159,8 @@ Example response: "subscribed" : false, "user_notes_count": 1, "due_date": null, - "web_url": "http://example.com/example/example/issues/1" + "web_url": "http://example.com/example/example/issues/1", + "confidential": false } ] ``` @@ -238,7 +240,8 @@ Example response: "subscribed" : false, "user_notes_count": 1, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/1" + "web_url": "http://example.com/example/example/issues/1", + "confidential": false } ] ``` @@ -303,7 +306,8 @@ Example response: "subscribed": false, "user_notes_count": 1, "due_date": null, - "web_url": "http://example.com/example/example/issues/1" + "web_url": "http://example.com/example/example/issues/1", + "confidential": false } ``` @@ -324,6 +328,7 @@ POST /projects/:id/issues | `id` | integer | yes | The ID of a project | | `title` | string | yes | The title of an issue | | `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | | `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 | @@ -362,7 +367,8 @@ Example response: "subscribed" : true, "user_notes_count": 0, "due_date": null, - "web_url": "http://example.com/example/example/issues/14" + "web_url": "http://example.com/example/example/issues/14", + "confidential": false } ``` @@ -385,6 +391,7 @@ PUT /projects/:id/issues/:issue_id | `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 | +| `confidential` | boolean | no | Updates an issue to be confidential | | `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 | @@ -424,7 +431,8 @@ Example response: "subscribed" : true, "user_notes_count": 0, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/15" + "web_url": "http://example.com/example/example/issues/15", + "confidential": false } ``` @@ -503,7 +511,8 @@ Example response: "web_url": "https://gitlab.example.com/u/solon.cremin" }, "due_date": null, - "web_url": "http://example.com/example/example/issues/11" + "web_url": "http://example.com/example/example/issues/11", + "confidential": false } ``` @@ -559,7 +568,8 @@ Example response: "web_url": "https://gitlab.example.com/u/solon.cremin" }, "due_date": null, - "web_url": "http://example.com/example/example/issues/11" + "web_url": "http://example.com/example/example/issues/11", + "confidential": false } ``` @@ -616,7 +626,8 @@ Example response: }, "subscribed": false, "due_date": null, - "web_url": "http://example.com/example/example/issues/12" + "web_url": "http://example.com/example/example/issues/12", + "confidential": false } ``` @@ -704,7 +715,8 @@ Example response: "upvotes": 0, "downvotes": 0, "due_date": null, - "web_url": "http://example.com/example/example/issues/110" + "web_url": "http://example.com/example/example/issues/110", + "confidential": false }, "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10", "body": "Vel voluptas atque dicta mollitia adipisci qui at.", -- cgit v1.2.1 From 9c3db830c033750c19197fe6a3f15a7705e2aa3b Mon Sep 17 00:00:00 2001 From: Ben Boeckel Date: Tue, 23 Aug 2016 13:29:59 -0400 Subject: entities: expose {,merge_commit_}sha in MergeRequest Fixes #20456. --- doc/api/merge_requests.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index f4760ceac7c..494040a1ce8 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -68,6 +68,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : false, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -135,6 +137,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": "9999999999999999999999999999999999999999", "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -238,6 +242,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -322,6 +328,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 0, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -397,6 +405,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -499,6 +509,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": "9999999999999999999999999999999999999999", "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -569,6 +581,8 @@ Parameters: "merge_when_build_succeeds": true, "merge_status": "can_be_merged", "subscribed" : true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, @@ -724,7 +738,9 @@ Example response: }, "merge_when_build_succeeds": false, "merge_status": "cannot_be_merged", - "subscribed": true + "subscribed": true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null } ``` @@ -798,7 +814,9 @@ Example response: }, "merge_when_build_succeeds": false, "merge_status": "cannot_be_merged", - "subscribed": false + "subscribed": false, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null } ``` @@ -891,6 +909,8 @@ Example response: "merge_when_build_succeeds": false, "merge_status": "unchecked", "subscribed": true, + "sha": "8888888888888888888888888888888888888888", + "merge_commit_sha": null, "user_notes_count": 7, "should_remove_source_branch": true, "force_remove_source_branch": false, -- cgit v1.2.1 From 636dbc85e24600849de9dd09c4854edf4adfe807 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 31 Aug 2016 17:40:54 +0200 Subject: The ID of a project can be also a string [ci skip] --- doc/api/commits.md | 14 +++++++------- doc/api/projects.md | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) (limited to 'doc/api') diff --git a/doc/api/commits.md b/doc/api/commits.md index 55d0de7afd9..682151d4b1d 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,7 +10,7 @@ GET /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch | | `since` | string | no | Only commits after or in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `until` | string | no | Only commits before or in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | @@ -58,7 +58,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -102,7 +102,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -138,7 +138,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -187,7 +187,7 @@ POST /projects/:id/repository/commits/:sha/comments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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 | @@ -232,7 +232,7 @@ GET /projects/:id/repository/commits/:sha/statuses | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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` @@ -306,7 +306,7 @@ POST /projects/:id/statuses/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user | `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 diff --git a/doc/api/projects.md b/doc/api/projects.md index 0d5aa61aa74..a62aaee14d7 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -535,7 +535,7 @@ POST /projects/:id/star | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -602,7 +602,7 @@ DELETE /projects/:id/star | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -673,7 +673,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" @@ -760,7 +760,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" -- cgit v1.2.1 From 9d4af1b14068aa77848b982372ddf9e11567ae5f Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Tue, 30 Aug 2016 16:47:44 -0300 Subject: Add BroadcastMessage API documentation --- doc/api/broadcast_messages.md | 158 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 doc/api/broadcast_messages.md (limited to 'doc/api') diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md new file mode 100644 index 00000000000..c3a9207a3ae --- /dev/null +++ b/doc/api/broadcast_messages.md @@ -0,0 +1,158 @@ +# Broadcast Messages + +> **Note:** This feature was introduced in GitLab 8.12. + +The broadcast message API is only accessible to administrators. All requests by +guests will respond with `401 Unauthorized`, and all requests by normal users +will respond with `403 Forbidden`. + +## Get all broadcast messages + +``` +GET /broadcast_messages +``` + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages +``` + +Example response: + +```json +[ + { + "message":"Example broadcast message", + "starts_at":"2016-08-24T23:21:16.078Z", + "ends_at":"2016-08-26T23:21:16.080Z", + "color":"#E75E40", + "font":"#FFFFFF", + "id":1, + "active": false + } +] +``` + +## Get a specific broadcast message + +``` +GET /broadcast_messages/:id +``` + +| Attribute | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------- | +| `id` | integer | yes | Broadcast message ID | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages/1 +``` + +Example response: + +```json +{ + "message":"Deploy in progress", + "starts_at":"2016-08-24T23:21:16.078Z", + "ends_at":"2016-08-26T23:21:16.080Z", + "color":"#cecece", + "font":"#FFFFFF", + "id":1, + "active":false +} +``` + +## Create a broadcast message + +Responds with `400 Bad request` when the `message` parameter is missing or the +`color` or `font` values are invalid, and `201 Created` when the broadcast +message was successfully created. + +``` +POST /broadcast_messages +``` + +| Attribute | Type | Required | Description | +| ----------- | -------- | -------- | ---------------------------------------------------- | +| `message` | string | yes | Message to display | +| `starts_at` | datetime | no | Starting time (defaults to current time) | +| `ends_at` | datetime | no | Ending time (defaults to one hour from current time) | +| `color` | string | no | Background color hex code | +| `font` | string | no | Foreground color hex code | + +```bash +curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages +``` + +Example response: + +```json +{ + "message":"Deploy in progress", + "starts_at":"2016-08-26T00:41:35.060Z", + "ends_at":"2016-08-26T01:41:35.060Z", + "color":"#cecece", + "font":"#FFFFFF", + "id":1, + "active": true +} +``` + +## Update a broadcast message + +``` +PUT /broadcast_messages/:id +``` + +| Attribute | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------- | +| `id` | integer | yes | Broadcast message ID | +| `message` | string | no | Message to display | +| `starts_at` | datetime | no | Starting time | +| `ends_at` | datetime | no | Ending time | +| `color` | string | no | Background color hex code | +| `font` | string | no | Foreground color hex code | + +```bash +curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages/1 +``` + +Example response: + +```json +{ + "message":"Update message", + "starts_at":"2016-08-26T00:41:35.060Z", + "ends_at":"2016-08-26T01:41:35.060Z", + "color":"#000", + "font":"#FFFFFF", + "id":1, + "active": true +} +``` + +## Delete a broadcast message + +``` +DELETE /broadcast_messages/:id +``` + +| Attribute | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------- | +| `id` | integer | yes | Broadcast message ID | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/broadcast_messages/1 +``` + +Example response: + +```json +{ + "message":"Update message", + "starts_at":"2016-08-26T00:41:35.060Z", + "ends_at":"2016-08-26T01:41:35.060Z", + "color":"#000", + "font":"#FFFFFF", + "id":1, + "active": true +} +``` -- cgit v1.2.1 From 61fbe7efe9972bf43287d7ca76d7ec63fd5798a5 Mon Sep 17 00:00:00 2001 From: "Z.J. van de Weg" Date: Sat, 3 Sep 2016 09:57:52 +0200 Subject: Add link on API docs index page [ci skip] --- doc/api/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 3e79cce0120..96d94e08487 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -11,9 +11,10 @@ following locations: - [Award Emoji](award_emoji.md) - [Branches](branches.md) - [Builds](builds.md) -- [Build triggers](build_triggers.md) +- [Build Triggers](build_triggers.md) - [Build Variables](build_variables.md) - [Commits](commits.md) +- [Deployments](deployments.md) - [Deploy Keys](deploy_keys.md) - [Groups](groups.md) - [Group Access Requests](access_requests.md) -- cgit v1.2.1