From 3db8cfefc79de501aefc447d8f4360b9f6656196 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Mon, 18 Jan 2016 09:45:50 +0100
Subject: [PATCH 1/3] Refactor system_hooks API documentation [ci skip]
---
doc/api/system_hooks.md | 96 +++++++++++++++++++++++++++++++----------
1 file changed, 73 insertions(+), 23 deletions(-)
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
+}
+```
--
GitLab
From 9eeda3da3dfa3b1e328ab139bd2b0a389dea5ef1 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Mon, 18 Jan 2016 09:48:19 +0100
Subject: [PATCH 2/3] 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(-)
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
--
GitLab
From 23a878c40ca8ca73d371c561bb4d2730551f3a38 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 24 Jan 2016 20:19:46 +0100
Subject: [PATCH 3/3] Clean up system hooks API documentation
[ci skip]
---
doc/api/system_hooks.md | 28 ++++++++++++++++++++++++----
1 file changed, 24 insertions(+), 4 deletions(-)
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
```
--
GitLab