api docs: Merge docs for sending stream and private messages.

templates/zerver/api/arguments.json

@@ -1,28 +1,8 @@
 {
-    "private-message.md": [
+    "send-message.md": [
         {
             "argument": "type",
-            "description": "The type of message to be sent. `private` for a private message and `stream` for a [stream message](/api/stream-message).",
+            "description": "The type of message to be sent. `stream` for a stream message and `private` for a private message.",
-            "required": true,
-            "example": "private"
-        },
-        {
-            "argument": "to",
-            "description": "A JSON-encoded list containing the usernames of the recipients.",
-            "required": true,
-            "example": "wdaher@example.com"
-        },
-        {
-            "argument": "content",
-            "description": "The content of the message. Maximum message size of 10000 bytes.",
-            "required": true,
-            "example": "Hello"
-        }
-    ],
-    "stream-message.md": [
-        {
-            "argument": "type",
-            "description": "The type of message to be sent. `stream` for a stream message and `private` for a [private message](/api/private-message).",
             "required": true,
             "example": "stream"
         },

templates/zerver/api/fixtures.json

@@ -271,11 +271,6 @@
         "result": "error",
         "stream": "nonexistent_stream"
     },
-    "private-message": {
-        "id": 134,
-        "msg": "",
-        "result": "success"
-    },
     "register-queue": {
         "last_event_id": -1,
         "msg": "",
@@ -308,7 +303,7 @@
         "rendered": "<p><strong>foo</strong></p>",
         "result": "success"
     },
-    "stream-message": {
+    "send-message": {
         "id": 134,
         "msg": "",
         "result": "success"

templates/zerver/api/index.md

@@ -4,14 +4,14 @@ Zulip's APIs allow you to integrate other services with Zulip.  This
 guide should help you find the API you need:
 
 * First, check if the tool you'd like to integrate with Zulip
-[already has a native integration](/integrations).
+  [already has a native integration](/integrations).
 * Next, check if [Zapier](https://zapier.com/apps) or
   [IFTTT](https://ifttt.com/search) has an integration;
   Zulip's native integrations with Zapier and IFTTT often allow
   integrating a new service with Zulip without writing any code.
 * If you'd like to send content into Zulip, you can
   [write a native incoming webhook integration](/api/incoming-webhooks-overview)
-  or use [Zulip's API for sending messages](/api/stream-message).
+  or use [Zulip's API for sending messages](/api/send-message).
 * If you're building an interactive bot that reacts to activity inside
   Zulip, you'll want to look at Zulip's
   [Python framework for interactive bots](/api/running-bots) or

templates/zerver/api/private-message.md

@@ -1,95 +0,0 @@
-# Private message
-
-Send a private message to a user or multiple users.
-
-`POST {{ api_url }}/v1/messages`
-
-## 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>
-<li data-language="zulip-send">zulip-send</li>
-</ul>
-<div class="blocks">
-
-<div data-language="curl" markdown="1">
-
-```
-curl {{ api_url }}/v1/messages \
-    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
-    -d "type=private" \
-    -d "to=hamlet@example.com" \
-    -d "content=I come not, friends, to steal away your hearts."
-```
-</div>
-
-<div data-language="python" markdown="1">
-
-{generate_code_example(python)|private-message|example}
-
-</div>
-
-<div data-language="zulip-send" markdown="1"> You can use `zulip-send`
-(available after you `pip install zulip`) to easily send Zulips from
-the command-line, providing the message content via STDIN.
-
-```bash
-zulip-send hamlet@example.com \
-    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
-```
-
-You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file.
-
-See also the [full API endpoint documentation](/api).
-</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',
-};
-
-zulip(config).then((client) => {
-    // Send a private message
-    const params = {
-        to: 'hamlet@example.com',
-        type: 'private',
-        content: 'I come not, friends, to steal away your hearts.',
-    }
-
-    client.messages.send(params).then(console.log);
-});
-
-```
-</div>
-
-</div>
-
-</div>
-
-## Arguments
-
-{generate_api_arguments_table|arguments.json|private-message.md}
-
-## Response
-
-#### Return values
-
-* `id`: The ID of the newly created message
-
-#### Example response
-
-A typical successful JSON response may look like:
-
-{generate_code_example|private-message|fixture}
-
-A typical failed JSON response for when the recipient's email
-address is invalid:
-
-{generate_code_example|invalid-pm-recipient-error|fixture}

templates/zerver/api/send-message.md

@@ -1,10 +1,11 @@
-# Stream message
+# Send a message
 
-Send a message to a stream.
+Send a stream or a private message.
 
 `POST {{ api_url }}/v1/messages`
 
 ## Usage examples
+
 <div class="code-section" markdown="1">
 <ul class="nav">
 <li data-language="python">Python</li>
@@ -17,19 +18,27 @@ Send a message to a stream.
 <div data-language="curl" markdown="1">
 
 ```
+# For stream messages
 curl {{ api_url }}/v1/messages \
     -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
     -d "type=stream" \
     -d "to=Denmark" \
     -d "subject=Castle" \
     -d "content=Something is rotten in the state of Denmark."
+
+# For private messages
+curl {{ api_url }}/v1/messages \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d "type=private" \
+    -d "to=hamlet@example.com" \
+    -d "content=I come not, friends, to steal away your hearts."
 ```
 
 </div>
 
 <div data-language="python" markdown="1">
 
-{generate_code_example(python)|stream-message|example}
+{generate_code_example(python)|send-message|example}
 
 </div>
 
@@ -38,24 +47,30 @@ curl {{ api_url }}/v1/messages \
 the command-line, providing the message content via STDIN.
 
 ```bash
+# For stream messages
 zulip-send --stream Denmark --subject Castle \
     --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
+
+# For private messages
+zulip-send hamlet@example.com \
+    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
 ```
 
 #### Passing in the message on the command-line
 
-If you'd like, you can also provide the message on the command-line with the `-m` flag, as follows:
+If you'd like, you can also provide the message on the command-line with the
+`-m` or `--message` flag, as follows:
 
 
 ```bash
 zulip-send --stream Denmark --subject Castle \
-    -m "Something is rotten in the state of Denmark." \
+    --message "Something is rotten in the state of Denmark." \
     --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
 ```
 
-You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file.
+You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc`
+file.
 
-See also the [full API endpoint documentation](/api).
 </div>
 
 <div data-language="javascript" markdown="1">
@@ -68,6 +83,7 @@ const config = {
     zuliprc: 'zuliprc-dev',
 };
 
+// Send a stream message
 zulip(config).then((client) => {
     // Send a message
     const params = {
@@ -80,6 +96,18 @@ zulip(config).then((client) => {
     client.messages.send(params).then(console.log);
 });
 
+// Send a private message
+zulip(config).then((client) => {
+    // Send a private message
+    const params = {
+        to: 'hamlet@example.com',
+        type: 'private',
+        content: 'I come not, friends, to steal away your hearts.',
+    }
+
+    client.messages.send(params).then(console.log);
+});
+
 ```
 </div>
 
@@ -89,7 +117,7 @@ zulip(config).then((client) => {
 
 ## Arguments
 
-{generate_api_arguments_table|arguments.json|stream-message.md}
+{generate_api_arguments_table|arguments.json|send-message.md}
 
 ## Response
 
@@ -100,8 +128,14 @@ zulip(config).then((client) => {
 #### Example response
 A typical successful JSON response may look like:
 
-{generate_code_example|stream-message|fixture}
+{generate_code_example|send-message|fixture}
 
-A typical failed JSON response for when the target stream does not exist:
+A typical failed JSON response for when a stream message is sent to a stream
+that does not exist:
 
 {generate_code_example|nonexistent-stream-error|fixture}
+
+A typical failed JSON response for when a private message is sent to a user
+that does not exist:
+
+{generate_code_example|invalid-pm-recipient-error|fixture}

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

@@ -1,7 +1,6 @@
 #### Messages
 
-* [Stream message](/api/stream-message)
+* [Send a message](/api/send-message)
-* [Private message](/api/private-message)
 * [Render message](/api/render-message)
 * [Update a message](/api/update-message)
 

zerver/lib/api_test_helpers.py

@@ -293,7 +293,7 @@ def render_message(client):
     fixture = FIXTURES['render-message']
     test_against_fixture(result, fixture)
 
-def stream_message(client):
+def send_message(client):
     # type: (Client) -> int
 
     # {code_example|start}
@@ -307,11 +307,34 @@ def stream_message(client):
     result = client.send_message(request)
     # {code_example|end}
 
-    fixture = FIXTURES['stream-message']
+    fixture = FIXTURES['send-message']
     test_against_fixture(result, fixture, check_if_equal=['result'],
                          check_if_exists=['id'])
 
-    # test it was actually sent
+    # test that the message was actually sent
+    message_id = result['id']
+    url = 'messages/' + str(message_id)
+    result = client.call_endpoint(
+        url=url,
+        method='GET'
+    )
+    assert result['result'] == 'success'
+    assert result['raw_content'] == request['content']
+
+    # {code_example|start}
+    # Send a private message
+    request = {
+        "type": "private",
+        "to": "iago@zulip.com",
+        "content": "I come not, friends, to steal away your hearts."
+    }
+    result = client.send_message(request)
+    # {code_example|end}
+
+    test_against_fixture(result, fixture, check_if_equal=['result'],
+                         check_if_exists=['id'])
+
+    # test that the message was actually sent
     message_id = result['id']
     url = 'messages/' + str(message_id)
     result = client.call_endpoint(
@@ -336,33 +359,6 @@ def test_nonexistent_stream_error(client):
     fixture = FIXTURES['nonexistent-stream-error']
     test_against_fixture(result, fixture)
 
-def private_message(client):
-    # type: (Client) -> None
-
-    # {code_example|start}
-    # Send a private message
-    request = {
-        "type": "private",
-        "to": "iago@zulip.com",
-        "content": "I come not, friends, to steal away your hearts."
-    }
-    result = client.send_message(request)
-    # {code_example|end}
-
-    fixture = FIXTURES['private-message']
-    test_against_fixture(result, fixture, check_if_equal=['result'],
-                         check_if_exists=['id'])
-
-    # test it was actually sent
-    message_id = result['id']
-    url = 'messages/' + str(message_id)
-    result = client.call_endpoint(
-        url=url,
-        method='GET'
-    )
-    assert result['result'] == 'success'
-    assert result['raw_content'] == request['content']
-
 def test_private_message_invalid_recipient(client):
     # type: (Client) -> None
     request = {
@@ -507,8 +503,7 @@ def test_invalid_stream_error(client):
 
 TEST_FUNCTIONS = {
     'render-message': render_message,
-    'stream-message': stream_message,
+    'send-message': send_message,
-    'private-message': private_message,
     '/messages/{message_id}:patch': update_message,
     'get-stream-id': get_stream_id,
     'get-subscribed-streams': list_subscriptions,
@@ -575,9 +570,8 @@ def test_messages(client, nonadmin_client):
     # type: (Client, Client) -> None
 
     render_message(client)
-    message_id = stream_message(client)
+    message_id = send_message(client)
     update_message(client, message_id)
-    private_message(client)
 
     test_nonexistent_stream_error(client)
     test_private_message_invalid_recipient(client)

zerver/tests/test_docs.py

@@ -78,8 +78,7 @@ class DocPageTest(ZulipTestCase):
         self._test('/api/', 'The Zulip API')
         self._test('/api/api-keys', 'you can use its email and API key')
         self._test('/api/installation-instructions', 'No download required!')
-        self._test('/api/private-message', 'steal away your hearts')
+        self._test('/api/send-message', 'steal away your hearts')
-        self._test('/api/stream-message', 'rotten in the state of Denmark')
         self._test('/api/render-message', '**foo**')
         self._test('/api/get-all-streams', 'include_public')
         self._test('/api/get-stream-id', 'The name of the stream to retrieve the ID for.')