Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

This commit is contained in:
Yago González 2018-06-18 17:44:48 +02:00 committed by Tim Abbott
parent 50ed378dd6
commit cb24756edc
8 changed files with 79 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
templates/zerver/api/arguments.json
View File

@ -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).",
"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).",
"description": "The type of message to be sent. `stream` for a stream message and `private` for a private message.",
"required": true,
"example": "stream"
},

7
templates/zerver/api/fixtures.json
View File

@ -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"

2
templates/zerver/api/index.md
View File

@ -11,7 +11,7 @@ guide should help you find the API you need:
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

95
templates/zerver/api/private-message.md
View File

@ -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}

54
templates/zerver/api/stream-message.md → templates/zerver/api/send-message.md
View File

@ -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}

3
templates/zerver/help/include/rest-endpoints.md
View File

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

62
zerver/lib/api_test_helpers.py
View File

@ -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,
'private-message': private_message,
'send-message': send_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)

3
zerver/tests/test_docs.py
View File

@ -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/stream-message', 'rotten in the state of Denmark')
self._test('/api/send-message', 'steal away your hearts')
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.')