api docs: Document the DELETE /api/v1/events endpoint.

Note that there is no JavaScript equivalent for requesting this
endpoint in zulip-js yet.

templates/zerver/api/arguments.json

@@ -172,5 +172,13 @@
             "required":"Optional",
             "example":"event_types=['message']"
         }
+    ],
+    "delete-queue.md":[
+        {
+            "argument":"queue_id",
+            "description":"The ID of a queue that you registered via `POST /api/v1/register`(see [Register a queue](/api/register-queue) and [Get events from queue](/api/get-events-from-queue)).",
+            "required":"Optional",
+            "example":"1375801870:2942"
+        }
     ]
 }

templates/zerver/api/delete-queue.md

@@ -0,0 +1,74 @@
+# Delete a queue
+
+Delete a previously registered queue.
+
+`DELETE {{ api_url }}/v1/events`
+
+## Arguments
+
+{generate_api_arguments_table|arguments.json|delete-queue.md}
+
+## Usage examples
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="curl">curl</li>
+<li data-language="python">Python</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl -X "DELETE" {{ api_url }}/v1/events \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+    -d 'queue_id=1515096410:1'
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+```
+#!/usr/bin/env python
+
+import zulip
+
+# Download ~/zuliprc-dev from your dev server
+client = zulip.Client(config_file="~/zuliprc-dev")
+
+# Delete a queue
+print(client.deregister(queue_id="1515096410:1"))
+```
+
+</div>
+
+</div>
+
+</div>
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+```
+{
+    'msg':'',
+    'result':'success'
+}
+```
+
+A typical JSON response for when the `queue_id` is non-existent or the
+associated queue has already been deleted:
+
+```
+{
+    'code':'BAD_EVENT_QUEUE_ID',
+    'queue_id':'1515096410:2',
+    'result':'error',
+    'msg':'Bad event queue id: 1515096410:2'
+}
+```
+
+{!invalid-api-key-json-response.md!}

templates/zerver/api/sidebar.md

@@ -22,6 +22,7 @@
 #### Events
 * [Register a queue](/api/register-queue)
 * [Get events from queue](/api/get-events-from-queue)
+* [Delete a queue](/api/delete-queue)
 
 ## Integrations
 

zerver/tests/test_docs.py

@@ -63,6 +63,7 @@ class DocPageTest(ZulipTestCase):
         self._test('/api/get-all-users', 'client_gravatar')
         self._test('/api/register-queue', 'apply_markdown')
         self._test('/api/get-events-from-queue', 'dont_block')
+        self._test('/api/delete-queue', 'Delete a previously registered queue')
         self._test('/team/', 'industry veterans')
         self._test('/history/', 'Cambridge, Massachusetts')
         # Test the i18n version of one of these pages.