Refactor broadcast message API pagedocs/uplift-broadcast-messages-api-doc

1 files changed, 66 insertions, 35 deletions

diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md
index fe370682308..357d9916ade 100644
--- a/doc/api/broadcast_messages.md
+++ b/doc/api/broadcast_messages.md
@@ -1,18 +1,25 @@
 # Broadcast Messages API
 
-> **Note:** This feature was introduced in GitLab 8.12.
+> 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`.
+Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md).
+
+The broadcast message API is only accessible to administrators. All requests by:
+
+- Guests will result in `401 Unauthorized`.
+- Regular users will result in `403 Forbidden`.
 
 ## Get all broadcast messages
 
-```
+List all broadcast messages.
+
+```text
 GET /broadcast_messages
 ```
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
 ```
 
@@ -34,15 +41,21 @@ Example response:
 
 ## Get a specific broadcast message
 
-```
+Get a specific broadcast message.
+
+```text
 GET /broadcast_messages/:id
 ```
 
-| Attribute   | Type     | Required | Description               |
-| ----------- | -------- | -------- | ------------------------- |
-| `id`        | integer  | yes      | Broadcast message ID      |
+Parameters:
+
+| Attribute | Type    | Required | Description                          |
+|:----------|:--------|:---------|:-------------------------------------|
+| `id`      | integer | yes      | ID of broadcast message to retrieve. |
+
+Example request:
 
-```bash
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```
 
@@ -62,19 +75,25 @@ Example response:
 
 ## Create a broadcast message
 
-```
+Create a new broadcast message.
+
+```text
 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                            |
+Parameters:
 
-```bash
+| 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.                            |
+
+Example request:
+
+```sh
 curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
 ```
 
@@ -94,20 +113,26 @@ Example response:
 
 ## Update a broadcast message
 
-```
+Update an existing broadcast message.
+
+```text
 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 |
+Parameters:
+
+| Attribute   | Type     | Required | Description                        |
+|:------------|:---------|:---------|:-----------------------------------|
+| `id`        | integer  | yes      | ID of broadcast message to update. |
+| `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
+Example request:
+
+```sh
 curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```
 
@@ -127,14 +152,20 @@ Example response:
 
 ## Delete a broadcast message
 
-```
+Delete a broadcast message.
+
+```sh
 DELETE /broadcast_messages/:id
 ```
 
-| Attribute   | Type     | Required | Description               |
-| ----------- | -------- | -------- | ------------------------- |
-| `id`        | integer  | yes      | Broadcast message ID      |
+Parameters:
+
+| Attribute | Type    | Required | Description                        |
+|:----------|:--------|:---------|:-----------------------------------|
+| `id`      | integer | yes      | ID of broadcast message to delete. |
+
+Example request:
 
-```bash
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```