summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md64
-rw-r--r--doc/api/branches.md4
-rw-r--r--doc/api/events.md2
-rw-r--r--doc/api/protected_branches.md145
4 files changed, 184 insertions, 31 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 1d2226e2ae8..8acb2145f1a 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -43,6 +43,7 @@ following locations:
- [Project Access Requests](access_requests.md)
- [Project Members](members.md)
- [Project Snippets](project_snippets.md)
+- [Protected Branches](protected_branches.md)
- [Repositories](repositories.md)
- [Repository Files](repository_files.md)
- [Runners](runners.md)
@@ -76,6 +77,38 @@ controller-specific endpoints. GraphQL has a number of benefits:
It will co-exist with the current v4 REST API. If we have a v5 API, this should
be a compatibility layer on top of GraphQL.
+## Basic usage
+
+API requests should be prefixed with `api` and the API version. The API version
+is defined in [`lib/api.rb`][lib-api-url]. For example, the root of the v4 API
+is at `/api/v4`.
+
+For endpoints that require [authentication](#authentication), you need to pass
+a `private_token` 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).
+
+Example of a valid API request:
+
+```
+GET /projects?private_token=9koXpg98eAheJpvBs5tK
+```
+
+Example of a valid API request using cURL and authentication via header:
+
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
+```
+
+Example of a valid API request using cURL and authentication via a query string:
+
+```shell
+curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
+```
+
+The API uses JSON to serialize data. You don't need to specify `.json` at the
+end of an API URL.
+
## Authentication
Most API requests require authentication via a session cookie or token. For
@@ -206,37 +239,6 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
```
-## Basic usage
-
-API requests should be prefixed with `api` and the API version. The API version
-is defined in [`lib/api.rb`][lib-api-url].
-
-For endpoints that require [authentication](#authentication), you need to pass
-a `private_token` 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).
-
-Example of a valid API request:
-
-```
-GET /projects?private_token=9koXpg98eAheJpvBs5tK
-```
-
-Example of a valid API request using cURL and authentication via header:
-
-```shell
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
-```
-
-Example of a valid API request using cURL and authentication via a query string:
-
-```shell
-curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
-```
-
-The API uses JSON to serialize data. You don't need to specify `.json` at the
-end of an API URL.
-
## Status codes
The API is designed to return different status codes according to context and
diff --git a/doc/api/branches.md b/doc/api/branches.md
index dfaa7d6fab7..80744258acb 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -95,6 +95,8 @@ Example response:
## Protect repository branch
+>**Note:** This API endpoint is deprecated in favor of `POST /projects/:id/protected_branches`.
+
Protects a single project repository branch. This is an idempotent function,
protecting an already protected repository branch still returns a `200 OK`
status code.
@@ -143,6 +145,8 @@ Example response:
## Unprotect repository branch
+>**Note:** This API endpoint is deprecated in favor of `DELETE /projects/:id/protected_branches/:name`
+
Unprotects a single project repository branch. This is an idempotent function,
unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
diff --git a/doc/api/events.md b/doc/api/events.md
index e7829c9f479..6e530317f6c 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -302,6 +302,7 @@ Example response:
"project_id":1,
"action_name":"opened",
"target_id":160,
+ "target_iid":160,
"target_type":"Issue",
"author_id":25,
"data":null,
@@ -322,6 +323,7 @@ Example response:
"project_id":1,
"action_name":"opened",
"target_id":159,
+ "target_iid":159,
"target_type":"Issue",
"author_id":21,
"data":null,
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
new file mode 100644
index 00000000000..10faa95d7e8
--- /dev/null
+++ b/doc/api/protected_branches.md
@@ -0,0 +1,145 @@
+# Protected branches API
+
+>**Note:** This feature was introduced in GitLab 9.5
+
+**Valid access levels**
+
+The access levels are defined in the `ProtectedBranchAccess::ALLOWED_ACCESS_LEVELS` constant. Currently, these levels are recognized:
+```
+0 => No access
+30 => Developer access
+40 => Master access
+```
+
+## List protected branches
+
+Gets a list of protected branches from a project.
+
+```
+GET /projects/:id/protected_branches
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches'
+```
+
+Example response:
+
+```json
+[
+ {
+ "name": "master",
+ "push_access_levels": [
+ {
+ "access_level": 40,
+ "access_level_description": "Masters"
+ }
+ ],
+ "merge_access_levels": [
+ {
+ "access_level": 40,
+ "access_level_description": "Masters"
+ }
+ ]
+ },
+ ...
+]
+```
+
+## Get a single protected branch or wildcard protected branch
+
+Gets a single protected branch or wildcard protected branch.
+
+```
+GET /projects/:id/protected_branches/:name
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name` | string | yes | The name of the branch or wildcard |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master'
+```
+
+Example response:
+
+```json
+{
+ "name": "master",
+ "push_access_levels": [
+ {
+ "access_level": 40,
+ "access_level_description": "Masters"
+ }
+ ],
+ "merge_access_levels": [
+ {
+ "access_level": 40,
+ "access_level_description": "Masters"
+ }
+ ]
+}
+```
+
+## Protect repository branches
+
+Protects a single repository branch or several project repository
+branches using a wildcard protected branch.
+
+```
+POST /projects/:id/protected_branches
+```
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name` | string | yes | The name of the branch or wildcard |
+| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, master access level) |
+| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, master access level) |
+
+Example response:
+
+```json
+{
+ "name": "*-stable",
+ "push_access_levels": [
+ {
+ "access_level": 30,
+ "access_level_description": "Developers + Masters"
+ }
+ ],
+ "merge_access_levels": [
+ {
+ "access_level": 30,
+ "access_level_description": "Developers + Masters"
+ }
+ ]
+}
+```
+
+## Unprotect repository branches
+
+Unprotects the given protected branch or wildcard protected branch.
+
+```
+DELETE /projects/:id/protected_branches/:name
+```
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable'
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name` | string | yes | The name of the branch |
View Lorry Controller Status