api docs: Document POST /typing.

templates/zerver/api/typing.md

@@ -0,0 +1,73 @@
+# Set "typing" status
+
+Send an event indicating that the user has started or stopped typing
+on their client.  See
+[the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html)
+for details on Zulip's typing notifications protocol.
+
+`POST {{ api_url }}/v1/typing`
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="javascript">JavaScript</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl -X POST {{ api_url }}/v1/typing \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d "op=start" \
+    -d 'to="iago@zulip.com","polonius@zulip.com"'
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/typing:post|example}
+
+</div>
+
+<div data-language="javascript" markdown="1">
+More examples and documentation can be found [here](https://github.com/zulip/zulip-js).
+```js
+const zulip = require('zulip-js');
+
+// Download zuliprc-dev from your dev server
+const config = {
+    zuliprc: 'zuliprc-dev',
+};
+
+const typingParams = {
+    op: 'start',
+    to: ['iago@zulip.com', 'polonius@zulip.com'],
+};
+
+zulip(config).then((client) => {
+    // The user has started to type in the group PM with Iago and Polonius
+    return client.typing.send(typingParams);
+}).then(console.log);
+```
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/typing:post}
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/typing:post|fixture(200)}

templates/zerver/help/include/rest-endpoints.md

@@ -20,6 +20,7 @@
 * [Get all users](/api/get-all-users)
 * [Get profile](/api/get-profile)
 * [Create a user](/api/create-user)
+* [Set "typing" status](/api/typing)
 
 #### Real-time events
 * [Real time events API](/api/real-time-events)

zerver/lib/api_test_helpers.py

@@ -445,6 +445,32 @@ def get_stream_topics(client, stream_id):
     validate_against_openapi_schema(result, '/users/me/{stream_id}/topics',
                                     'get', '200')
 
+def set_typing_status(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # The user has started to type in the group PM with Iago and Polonius
+    request = {
+        'op': 'start',
+        'to': ['iago@zulip.com', 'polonius@zulip.com']
+    }
+    result = client.set_typing_status(request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/typing', 'post', '200')
+
+    # {code_example|start}
+    # The user has finished typing in the group PM with Iago and Polonius
+    request = {
+        'op': 'stop',
+        'to': ['iago@zulip.com', 'polonius@zulip.com']
+    }
+    result = client.set_typing_status(request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/typing', 'post', '200')
+
+
 def test_invalid_api_key(client_with_invalid_key):
     # type: (Client) -> None
     result = client_with_invalid_key.list_subscriptions()
@@ -479,7 +505,8 @@ TEST_FUNCTIONS = {
     '/register:post': register_queue,
     '/events:delete': deregister_queue,
     '/user_uploads:post': upload_file,
-    '/users/me/{stream_id}/topics:get': get_stream_topics
+    '/users/me/{stream_id}/topics:get': get_stream_topics,
+    '/typing:post': set_typing_status,
 }
 
 # SETUP METHODS FOLLOW
@@ -548,6 +575,7 @@ def test_users(client):
     get_members(client)
     get_profile(client)
     upload_file(client)
+    set_typing_status(client)
 
 def test_streams(client, nonadmin_client):
     # type: (Client, Client) -> None

zerver/openapi/zulip.yaml

@@ -1012,7 +1012,42 @@ paths:
                         "msg": "User not authorized for this query",
                         "result": "error"
                     }
-
+  /typing:
+    post:
+      description: Send an event indicating that the user has started or
+        stopped typing on their client.
+      parameters:
+      - name: op
+        in: query
+        description: Whether the user has started (`start`) or stopped (`stop`)
+          to type.
+        schema:
+          type: string
+          enum:
+          - start
+          - stop
+        example: start
+        required: true
+      - name: notification_to
+        in: query
+        description: The recipients of the message being typed, in the same format used by the
+          send_message API.  Typing notifications are only supported for private messages,
+          so this should be a JSON-encoded list of email addresses of the message's recipients.
+        schema:
+          type: array
+          items:
+            type: string
+        example: ["iago@zulip.com", "polonius@zulip.com"]
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JsonSuccess'
 components:
   #######################
   # Security definitions