Commit 5c8bd42c authored by Evan Read's avatar Evan Read

Refactor broadcast message API page

parent 7f880007
# Broadcast Messages API # 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 Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md).
guests will respond with `401 Unauthorized`, and all requests by normal users
will respond with `403 Forbidden`. 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 ## Get all broadcast messages
``` List all broadcast messages.
```text
GET /broadcast_messages GET /broadcast_messages
``` ```
```bash Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
``` ```
...@@ -34,15 +41,21 @@ Example response: ...@@ -34,15 +41,21 @@ Example response:
## Get a specific broadcast message ## Get a specific broadcast message
``` Get a specific broadcast message.
```text
GET /broadcast_messages/:id GET /broadcast_messages/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------- | |:----------|:--------|:---------|:-------------------------------------|
| `id` | integer | yes | Broadcast message ID | | `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 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
``` ```
...@@ -62,19 +75,25 @@ Example response: ...@@ -62,19 +75,25 @@ Example response:
## Create a broadcast message ## Create a broadcast message
``` Create a new broadcast message.
```text
POST /broadcast_messages POST /broadcast_messages
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ----------- | -------- | -------- | ---------------------------------------------------- | |:------------|:---------|:---------|:------------------------------------------------------|
| `message` | string | yes | Message to display | | `message` | string | yes | Message to display. |
| `starts_at` | datetime | no | Starting time (defaults to current time) | | `starts_at` | datetime | no | Starting time (defaults to current time). |
| `ends_at` | datetime | no | Ending time (defaults to one hour from current time) | | `ends_at` | datetime | no | Ending time (defaults to one hour from current time). |
| `color` | string | no | Background color hex code | | `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground color hex code | | `font` | string | no | Foreground color hex code. |
```bash 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 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: ...@@ -94,20 +113,26 @@ Example response:
## Update a broadcast message ## Update a broadcast message
``` Update an existing broadcast message.
```text
PUT /broadcast_messages/:id PUT /broadcast_messages/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------- | |:------------|:---------|:---------|:-----------------------------------|
| `id` | integer | yes | Broadcast message ID | | `id` | integer | yes | ID of broadcast message to update. |
| `message` | string | no | Message to display | | `message` | string | no | Message to display. |
| `starts_at` | datetime | no | Starting time | | `starts_at` | datetime | no | Starting time. |
| `ends_at` | datetime | no | Ending time | | `ends_at` | datetime | no | Ending time. |
| `color` | string | no | Background color hex code | | `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground 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 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: ...@@ -127,14 +152,20 @@ Example response:
## Delete a broadcast message ## Delete a broadcast message
``` Delete a broadcast message.
```sh
DELETE /broadcast_messages/:id DELETE /broadcast_messages/:id
``` ```
Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------- | |:----------|:--------|:---------|:-----------------------------------|
| `id` | integer | yes | Broadcast message ID | | `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 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
``` ```
...@@ -4,6 +4,8 @@ GitLab can display messages to all users of a GitLab instance in a banner that a ...@@ -4,6 +4,8 @@ GitLab can display messages to all users of a GitLab instance in a banner that a
![Broadcast Message](img/broadcast_messages.png) ![Broadcast Message](img/broadcast_messages.png)
Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md).
NOTE: **Note:** NOTE: **Note:**
If more than one banner message is active at one time, they are displayed in a stack in order of creation. If more than one banner message is active at one time, they are displayed in a stack in order of creation.
......
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