doc(api): document announcement endpoint

1 files changed, 99 insertions, 0 deletions

diff --git a/README.adoc b/README.adoc
index 13d2156..ace2cc5 100644
--- a/README.adoc
+++ b/README.adoc
@@ -145,6 +145,105 @@ authenticate itself:
 | 415          | Request body too big
 |=============================================
 
+GET `/api/v2/announcement`
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+|=============================================
+| Request Content-Type  | none
+| Response Content-Type | `application/json`
+| Authentication        | no
+|=============================================
+
+The endpoint can be used to query the current announcement
+text. If one exists, the following response format is used:
+
+---------------------------
+{
+  "announcement": "some announcement text"
+}
+---------------------------
+
+If however no announcement text has been set (or it has been
+deleted), the response looks like this and is returned with
+a response status of 404:
+
+---------------------------
+{
+  "announcement": null
+}
+---------------------------
+
+|=============================================
+| HTTP Status  | Meaning
+| 200          | Success
+| 404          | No announcement text is set
+|=============================================
+
+PUT `/api/v2/announcement`
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+|=============================================
+| Request Content-Type  | `application/x-www-form-urlencoded`
+| Response Content-Type | `application/json`
+| Authentication        | yes (see below)
+|=============================================
+
+This endpoint allows you to set the announcement
+text which will be displayed on the panel (if
+enabled) during times when the queue is empty.
+
+Since the API call overwrites previous content,
+it requires authentication additionally. Any
+call to this endpoint must send a form with
+the following fields:
+
+|=============================================
+| `text`  | text to be added to the queue
+| `token` | API token of the application
+|=============================================
+
+The response contains the announcement in the
+same format as the `GET` variant of this endpoint,
+except it's guaranteed to never be `null`:
+
+----------------------
+{
+  "announcement": "new announcement"
+}
+----------------------
+
+|=============================================
+| HTTP Status  | Meaning
+| 200          | Success, announcement set
+| 400          | Illegal method or malformed request
+| 415          | Request body too big or text field longer allowed (usually 512 bytes)
+|=============================================
+
+DELETE `/api/v2/announcement`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+|=============================================
+| Request Content-Type  | `application/x-www-form-urlencoded`
+| Response Content-Type | none
+| Authentication        | yes (see below)
+|=============================================
+
+This endpoint can be used to delete the announcement text.
+The request should send a form with the following fields
+as request body in order to authenticate itself:
+
+|=============================================
+| `token` | API token of the application
+|=============================================
+
+|=============================================
+| HTTP Status  | Meaning
+| 204          | Success, queue entry deleted
+| 400          | Illegal method or malformed request
+| 401          | Unauthorized API token
+| 415          | Request body too big
+|=============================================
+
 API `v1`
 ~~~~~~~