summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Speicher <rspeicher@gmail.com>2016-08-30 16:47:44 -0300
committerRobert Speicher <rspeicher@gmail.com>2016-08-31 17:03:19 -0300
commit9d4af1b14068aa77848b982372ddf9e11567ae5f (patch)
tree49a9db35168652c1500168ac6ca82e95ce48a9c1
parent6a58af3a4a1c3122d57238505898f61c40bf7b54 (diff)
downloadgitlab-ce-9d4af1b14068aa77848b982372ddf9e11567ae5f.tar.gz
Add BroadcastMessage API documentation
-rw-r--r--doc/api/broadcast_messages.md158
1 files changed, 158 insertions, 0 deletions
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
+}
+```