From 54aa87fba34dd59875e7f86a74868512700a35b9 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Fri, 10 Nov 2017 17:49:43 -0800 Subject: [PATCH] api: Migrate to using the new version of the API site. --- templates/zerver/api.html | 214 -------------------------------- templates/zerver/api/main.html | 4 +- templates/zerver/api/sidebar.md | 6 +- zerver/tests/test_docs.py | 7 +- zproject/urls.py | 4 +- 5 files changed, 10 insertions(+), 225 deletions(-) delete mode 100644 templates/zerver/api.html diff --git a/templates/zerver/api.html b/templates/zerver/api.html deleted file mode 100644 index 752c081384..0000000000 --- a/templates/zerver/api.html +++ /dev/null @@ -1,214 +0,0 @@ -{% extends "zerver/portico.html" %} - -{# API information page #} - -{% block portico_content %} -

We hear you like APIs...

- -

We have a well-documented API that allows you to build custom integrations, in addition to our existing integrations. For ease-of-use, we've created a Python module that you can drop in to a project to start interacting with our API. There is also a JavaScript library that can be used either in the browser or in Node.js.

- -

Don't want to make it yourself? Zulip already integrates with lots of services.

- -

 

- -

Installation instructions

-

Python

-

Install it with pip:

- 
pip install zulip
-

JavaScript

-

Install it with npm:

- 
npm install zulip-js
- -

Usage examples

- - - -
- -
-

No download required!

- -{# -These code snippets are generated using our very own Zulip tool, by -sending them to myself in a code block, and then using the inspector -to pull out the resulting HTML :) - -Sample steps to do: -1. Write code in Zulip message box. -2. Put it in a multiline codeblock and specify a language. -3. Click on 'preview'. -4. Inspect and copy the HTML. - -#} - -

Stream message

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

Private message

-
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."
-
- -
- -
-
#!/usr/bin/env python
-
-import zulip
-import sys
-
-# Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc
-client = zulip.Client(email="othello-bot@example.com",
-                      api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
-                      site="{{ api_url }}")
-# Send a stream message
-client.send_message({
-    "type": "stream",
-    "to": "Denmark",
-    "subject": "Castle",
-    "content": "Something is rotten in the state of Denmark."
-})
-# Send a private message
-client.send_message({
-    "type": "private",
-    "to": "hamlet@example.com",
-    "content": "I come not, friends, to steal away your hearts."
-})
-
-# Print each message the user receives
-# This is a blocking call that will run forever
-client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n"))
-
-# Print every event relevant to the user
-# This is a blocking call that will run forever
-# This will never be reached unless you comment out the previous line
-client.call_on_each_event(lambda msg: sys.stdout.write(str(msg) + "\n"))
-
-
- - -
-

You can use zulip-send (found in bin/ in the tarball) to easily send Zulips from the command-line, providing the message to be sent on STDIN.

- -

Stream message

-
zulip-send --stream Denmark --subject Castle \
---user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ api_url }}
- -

Private message

-
zulip-send hamlet@example.com \
---user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ api_url }}
- -

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:

-
zulip-send --stream Denmark --subject Castle \
--m "Something is rotten in the state of Denmark." \
---user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ api_url }}
-
- -

You can omit the user, api-key, and - site arguments if you have a - ~/.zuliprc file. -

-

See also the full API endpoint documentation.

-
- -
-

More examples and documentation can be found here.

- -
const zulip = require('zulip');
-
-const config = {
-  username: 'othello-bot@example.com',
-  apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5',
-  realm: '{{ api_url }}'
-};
-
-const client = zulip(config);
-
-// Send a message
-client.messages.send({
-  to: 'Denmark',
-  type: 'stream',
-  subject: 'Castle',
-  content: 'Something is rotten in the state of Denmark.'
-});
-
-// Send a private message
-client.messages.send({
-  to: 'hamlet@example.com',
-  type: 'private',
-  content: 'I come not, friends, to steal away your hearts.'
-});
-
-// Register queue to receive messages for user
-client.queues.register({
-  event_types: ['message']
-}).then((res) => {
-  // Retrieve events from a queue
-  // Blocking until there is an event (or the request times out)
-  client.events.retrieve({
-    queue_id: res.queue_id,
-    last_event_id: -1,
-    dont_block: false
-  }).then(console.log);
-});
-
- -
-

 

- -

API keys

- -

You can create bots on your settings page. - Once you have a bot, you can use its email and API key to send messages.

- -

Create a bot:

- - -

Look for the bot's email and API key:

- - -

If you prefer to send messages as your own user, you can also find your API key on your settings page.

-

When using our python bindings, you may either specify the user - and API key for each Client object that you initialize, or let the binding look for - them in your ~/.zuliprc, the default config file, which you can create as follows:

-
[api]
-key=BOT_API_KEY
-email=BOT_EMAIL_ADDRESS
-site={{ api_url }}
- -

Additionally, you can also specify the parameters as environment variables as follows:

-
export ZULIP_CONFIG=/path/to/zulipconfig
-export ZULIP_EMAIL=BOT_EMAIL_ADDRESS
-export ZULIP_API_KEY=BOT_API_KEY
-
-

The parameters specified in environment variables would override the parameters provided in the config file. For example, if you specify the variable key in the config file and specify ZULIP_API_KEY as an environment variable, the value of ZULIP_API_KEY would be considered.

-

The following variables can be specified: -
1. ZULIP_CONFIG -
2. ZULIP_API_KEY -
3. ZULIP_EMAIL -
4. ZULIP_SITE -
5. ZULIP_CERT -
6. ZULIP_CERT_KEY -
7. ZULIP_CERT_BUNDLE -

- -
-{% endblock %} diff --git a/templates/zerver/api/main.html b/templates/zerver/api/main.html index d87cf756d5..a978a9bb69 100644 --- a/templates/zerver/api/main.html +++ b/templates/zerver/api/main.html @@ -5,7 +5,7 @@ {% block portico_content %}
-

Index

+

Index

{{ render_markdown_path("zerver/api/sidebar.md") }}
@@ -19,7 +19,7 @@