Commit 82e352d0 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'doc_refactor_branches_api' into 'master'

Refactor branches API documentation



See merge request !2464
parents d6682663 68755a23
...@@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically. ...@@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically.
GET /projects/:id/repository/branches 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 ```json
[ [
{ {
"name": "master",
"protected": true,
"commit": { "commit": {
"author_email": "john@example.com", "author_email": "john@example.com",
"author_name": "John Smith", "author_name": "John Smith",
...@@ -27,10 +35,9 @@ Parameters: ...@@ -27,10 +35,9 @@ Parameters:
"parent_ids": [ "parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8" "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
] ]
},
"name": "master",
"protected": true
} }
},
...
] ]
``` ```
...@@ -42,13 +49,21 @@ Get a single project repository branch. ...@@ -42,13 +49,21 @@ Get a single project repository branch.
GET /projects/:id/repository/branches/: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 |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master
```
- `id` (required) - The ID of a project Example response:
- `branch` (required) - The name of the branch
```json ```json
{ {
"name": "master",
"protected": true,
"commit": { "commit": {
"author_email": "john@example.com", "author_email": "john@example.com",
"author_name": "John Smith", "author_name": "John Smith",
...@@ -61,25 +76,30 @@ Parameters: ...@@ -61,25 +76,30 @@ Parameters:
"parent_ids": [ "parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8" "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
] ]
}, }
"name": "master",
"protected": true
} }
``` ```
## Protect repository branch ## Protect repository branch
Protects a single project repository branch. This is an idempotent function, protecting an already Protects a single project repository branch. This is an idempotent function,
protected repository branch still returns a `200 OK` status code. protecting an already protected repository branch still returns a `200 OK`
status code.
``` ```
PUT /projects/:id/repository/branches/:branch/protect 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
```
| 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 Example response:
- `branch` (required) - The name of the branch
```json ```json
{ {
...@@ -103,17 +123,24 @@ Parameters: ...@@ -103,17 +123,24 @@ Parameters:
## Unprotect repository branch ## Unprotect repository branch
Unprotects a single project repository branch. This is an idempotent function, unprotecting an already Unprotects a single project repository branch. This is an idempotent function,
unprotected repository branch still returns a `200 OK` status code. unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
``` ```
PUT /projects/:id/repository/branches/:branch/unprotect 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
```
- `id` (required) - The ID of a project | Attribute | Type | Required | Description |
- `branch` (required) - The name of the branch | --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `branch` | string | yes | The name of the branch |
Example response:
```json ```json
{ {
...@@ -141,11 +168,17 @@ Parameters: ...@@ -141,11 +168,17 @@ Parameters:
POST /projects/:id/repository/branches 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 Example response:
- `branch_name` (required) - The name of the branch
- `ref` (required) - Create branch from commit SHA or existing branch
```json ```json
{ {
...@@ -162,12 +195,13 @@ Parameters: ...@@ -162,12 +195,13 @@ Parameters:
"4ad91d3c1144c406e50c7b33bae684bd6837faf8" "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
] ]
}, },
"name": "master", "name": "newbranch",
"protected": false "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 ## Delete repository branch
...@@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason. ...@@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason.
DELETE /projects/:id/repository/branches/:branch 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 It returns `200` if it succeeds, `404` if the branch to be deleted does not exist
- `branch` (required) - The name of the branch 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 ```bash
or 400 for other reasons. In case of an error, an explaining message is provided. curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
```
Success response: Example response:
```json ```json
{ {
"branch_name": "my-removed-branch" "branch_name": "newbranch"
} }
``` ```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment