mirror of https://github.com/zulip/zulip.git
api: Migrate to using the new version of the API site.
This commit is contained in:
Tim Abbott
parent
01a8dd04d3
commit
54aa87fba3
|
|
@ -1,214 +0,0 @@
|
|||
{% extends "zerver/portico.html" %}
|
||||
|
||||
{# API information page #}
|
||||
|
||||
{% block portico_content %}
|
||||
<h1 class="api-page-header">We hear you like APIs...</h1>
|
||||
|
||||
<p>We have a <a href="/api/endpoints">well-documented API</a> that allows you to build custom integrations, in addition to our <a href="/integrations">existing integrations</a>. 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 <a href="https://github.com/zulip/zulip-js">JavaScript library</a> that can be used either in the browser or in Node.js.</p>
|
||||
|
||||
<p><strong>Don't want to make it yourself?</strong> Zulip <a href="/integrations">already integrates with lots of services</a>.</p>
|
||||
|
||||
<p> </p>
|
||||
|
||||
<h3>Installation instructions</h3>
|
||||
<h4>Python</h4>
|
||||
<p>Install it with <a href="https://pypi.python.org/pypi/zulip/">pip</a>:</p>
|
||||
<pre><code>pip install zulip</code></pre>
|
||||
<h4>JavaScript</h4>
|
||||
<p>Install it with <a href="https://www.npmjs.com/package/zulip-js">npm</a>:</p>
|
||||
<pre><code>npm install zulip-js</code></pre>
|
||||
|
||||
<h3>Usage examples</h3>
|
||||
|
||||
<ul class="nav nav-tabs" id="api-example-tabs">
|
||||
<li class="active"><a href="#curl" data-toggle="tab">curl</a></li>
|
||||
<li><a href="#python" data-toggle="tab">Python</a></li>
|
||||
<li><a href="#commandline" data-toggle="tab">zulip-send</a></li>
|
||||
<li><a href="#javascript" data-toggle="tab">JavaScript</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="tab-content">
|
||||
|
||||
<div class="tab-pane active" id="curl">
|
||||
<p>No download required!</p>
|
||||
|
||||
{#
|
||||
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.
|
||||
|
||||
#}
|
||||
|
||||
<h4>Stream message</h4>
|
||||
<div class="codehilite"><pre>curl {{ api_url }}/v1/messages <span class="se">\</span>
|
||||
-u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
|
||||
-d <span class="s2">"type=stream"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"to=Denmark"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"subject=Castle"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"content=Something is rotten in the state of Denmark."</span></pre>
|
||||
</div>
|
||||
|
||||
<h4>Private message</h4>
|
||||
<div class="codehilite"><pre>curl {{ api_url }}/v1/messages <span class="se">\</span>
|
||||
-u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
|
||||
-d <span class="s2">"type=private"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"to=hamlet@example.com"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"content=I come not, friends, to steal away your hearts."</span></pre>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="tab-pane" id="python">
|
||||
<div class="codehilite"><pre><span class="c">#!/usr/bin/env python</span>
|
||||
|
||||
<span class="kn">import</span> <span class="nn">zulip</span>
|
||||
<span class="kn">import</span> <span class="nn">sys</span>
|
||||
|
||||
<span class="c"># Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc</span>
|
||||
<span class="n">client</span> <span class="o">=</span> <span class="n">zulip</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="p">email</span><span class="o">=</span><span class="s">"othello-bot@example.com"</span><span class="p">,</span>
|
||||
<span class="n">api_key</span><span class="o">=</span><span class="s">"a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5"</span><span class="p">,</span>
|
||||
<span class="n">site</span><span class="o">=</span><span class="s">"{{ api_url }}"</span><span class="p">)</span>
|
||||
<span class="c"># Send a stream message</span>
|
||||
<span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">({</span>
|
||||
<span class="s">"type"</span><span class="p">:</span> <span class="s">"stream"</span><span class="p">,</span>
|
||||
<span class="s">"to"</span><span class="p">:</span> <span class="s">"Denmark"</span><span class="p">,</span>
|
||||
<span class="s">"subject"</span><span class="p">:</span> <span class="s">"Castle"</span><span class="p">,</span>
|
||||
<span class="s">"content"</span><span class="p">:</span> <span class="s">"Something is rotten in the state of Denmark."</span>
|
||||
<span class="p">})</span>
|
||||
<span class="c"># Send a private message</span>
|
||||
<span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">({</span>
|
||||
<span class="s">"type"</span><span class="p">:</span> <span class="s">"private"</span><span class="p">,</span>
|
||||
<span class="s">"to"</span><span class="p">:</span> <span class="s">"hamlet@example.com"</span><span class="p">,</span>
|
||||
<span class="s">"content"</span><span class="p">:</span> <span class="s">"I come not, friends, to steal away your hearts."</span>
|
||||
<span class="p">})</span>
|
||||
|
||||
<span class="c"># Print each message the user receives</span>
|
||||
<span class="c"># This is a blocking call that will run forever</span>
|
||||
<span class="n">client</span><span class="o">.</span><span class="n">call_on_each_message</span><span class="p">(</span><span class="k">lambda</span> <span class="n">msg</span><span class="p">:</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">))</span>
|
||||
|
||||
<span class="c"># Print every event relevant to the user</span>
|
||||
<span class="c"># This is a blocking call that will run forever</span>
|
||||
<span class="c"># This will never be reached unless you comment out the previous line</span>
|
||||
<span class="n">client</span><span class="o">.</span><span class="n">call_on_each_event</span><span class="p">(</span><span class="k">lambda</span> <span class="n">msg</span><span class="p">:</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
|
||||
|
||||
<div class="tab-pane" id="commandline">
|
||||
<p>You can use <code>zulip-send</code> (found in <code>bin/</code> in the tarball) to easily send Zulips from the command-line, providing the message to be sent on STDIN.</p>
|
||||
|
||||
<h4>Stream message</h4>
|
||||
<div class="codehilite"><pre>zulip-send --stream Denmark --subject Castle \
|
||||
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
|
||||
--site={{ api_url }}</pre></div>
|
||||
|
||||
<h4>Private message</h4>
|
||||
<div class="codehilite"><pre>zulip-send hamlet@example.com \
|
||||
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
|
||||
--site={{ api_url }}</pre></div>
|
||||
|
||||
<h4>Passing in the message on the command-line</h4>
|
||||
<p>If you'd like, you can also provide the message on the command-line with the <code>-m</code> flag, as follows:</p>
|
||||
<div class="codehilite"><pre>zulip-send --stream Denmark --subject Castle \
|
||||
-m <span class="s2">"Something is rotten in the state of Denmark."</span> \
|
||||
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
|
||||
--site={{ api_url }}
|
||||
</pre></div>
|
||||
|
||||
<p>You can omit the <code>user</code>, <code>api-key</code>, and
|
||||
<code>site</code> arguments if you have a
|
||||
<code>~/.zuliprc</code> file.
|
||||
</p>
|
||||
<p>See also the <a href="/api/endpoints">full API endpoint documentation.</a></p>
|
||||
</div>
|
||||
|
||||
<div class="tab-pane" id="javascript">
|
||||
<p>More examples and documentation can be found <a href="https://github.com/zulip/zulip-js">here</a>.</p>
|
||||
|
||||
<div class="codehilite"><pre><span class="kr">const</span> <span class="nx">zulip</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'zulip'</span><span class="p">);</span>
|
||||
|
||||
<span class="kr">const</span> <span class="nx">config</span> <span class="o">=</span> <span class="p">{</span>
|
||||
<span class="nx">username</span><span class="o">:</span> <span class="s1">'othello-bot@example.com'</span><span class="p">,</span>
|
||||
<span class="nx">apiKey</span><span class="o">:</span> <span class="s1">'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5'</span><span class="p">,</span>
|
||||
<span class="nx">realm</span><span class="o">:</span> <span class="s1">'{{ api_url }}'</span>
|
||||
<span class="p">};</span>
|
||||
|
||||
<span class="kr">const</span> <span class="nx">client</span> <span class="o">=</span> <span class="nx">zulip</span><span class="p">(</span><span class="nx">config</span><span class="p">);</span>
|
||||
|
||||
<span class="c1">// Send a message</span>
|
||||
<span class="nx">client</span><span class="p">.</span><span class="nx">messages</span><span class="p">.</span><span class="nx">send</span><span class="p">({</span>
|
||||
<span class="nx">to</span><span class="o">:</span> <span class="s1">'Denmark'</span><span class="p">,</span>
|
||||
<span class="nx">type</span><span class="o">:</span> <span class="s1">'stream'</span><span class="p">,</span>
|
||||
<span class="nx">subject</span><span class="o">:</span> <span class="s1">'Castle'</span><span class="p">,</span>
|
||||
<span class="nx">content</span><span class="o">:</span> <span class="s1">'Something is rotten in the state of Denmark.'</span>
|
||||
<span class="p">});</span>
|
||||
|
||||
<span class="c1">// Send a private message</span>
|
||||
<span class="nx">client</span><span class="p">.</span><span class="nx">messages</span><span class="p">.</span><span class="nx">send</span><span class="p">({</span>
|
||||
<span class="nx">to</span><span class="o">:</span> <span class="s1">'hamlet@example.com'</span><span class="p">,</span>
|
||||
<span class="nx">type</span><span class="o">:</span> <span class="s1">'private'</span><span class="p">,</span>
|
||||
<span class="nx">content</span><span class="o">:</span> <span class="s1">'I come not, friends, to steal away your hearts.'</span>
|
||||
<span class="p">});</span>
|
||||
|
||||
<span class="c1">// Register queue to receive messages for user</span>
|
||||
<span class="nx">client</span><span class="p">.</span><span class="nx">queues</span><span class="p">.</span><span class="nx">register</span><span class="p">({</span>
|
||||
<span class="nx">event_types</span><span class="o">:</span> <span class="p">[</span><span class="s1">'message'</span><span class="p">]</span>
|
||||
<span class="p">}).</span><span class="nx">then</span><span class="p">((</span><span class="nx">res</span><span class="p">)</span> <span class="o">=></span> <span class="p">{</span>
|
||||
<span class="c1">// Retrieve events from a queue</span>
|
||||
<span class="c1">// Blocking until there is an event (or the request times out)</span>
|
||||
<span class="nx">client</span><span class="p">.</span><span class="nx">events</span><span class="p">.</span><span class="nx">retrieve</span><span class="p">({</span>
|
||||
<span class="nx">queue_id</span><span class="o">:</span> <span class="nx">res</span><span class="p">.</span><span class="nx">queue_id</span><span class="p">,</span>
|
||||
<span class="nx">last_event_id</span><span class="o">:</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span>
|
||||
<span class="nx">dont_block</span><span class="o">:</span> <span class="kc">false</span>
|
||||
<span class="p">}).</span><span class="nx">then</span><span class="p">(</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">);</span>
|
||||
<span class="p">});</span>
|
||||
</pre></div>
|
||||
|
||||
</div>
|
||||
<p> </p>
|
||||
|
||||
<h3>API keys</h3>
|
||||
<a name="api_keys"></a>
|
||||
<p>You can create bots on your <a href="/#settings" target="_blank">settings page</a>.
|
||||
Once you have a bot, you can use its email and API key to send messages.</p>
|
||||
|
||||
<p>Create a bot:</p>
|
||||
<img class="screenshot" src="/static/images/api/create-bot.png" />
|
||||
|
||||
<p>Look for the bot's email and API key:</p>
|
||||
<img class="screenshot" src="/static/images/api/bot-key.png" />
|
||||
|
||||
<p>If you prefer to send messages as your own user, you can also find your API key on your <a href="/#settings" target="_blank">settings page</a>.</p>
|
||||
<p>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 <code>~/.zuliprc</code>, the default config file, which you can create as follows:</p>
|
||||
<div class="codehilite"><pre><span class="k">[api]</span>
|
||||
<span class="na">key</span><span class="o">=</span><span class="s">BOT_API_KEY</span>
|
||||
<span class="na">email</span><span class="o">=</span><span class="s">BOT_EMAIL_ADDRESS</span>
|
||||
<span class="na">site</span><span class="o">=</span><span class="s">{{ api_url }}</span></pre></div>
|
||||
|
||||
<p>Additionally, you can also specify the parameters as environment variables as follows:</p>
|
||||
<div class="codehilite"><pre><span></span><span class="nb">export</span> <span class="nv">ZULIP_CONFIG</span><span class="o">=</span>/path/to/zulipconfig
|
||||
<span class="nb">export</span> <span class="nv">ZULIP_EMAIL</span><span class="o">=</span>BOT_EMAIL_ADDRESS
|
||||
<span class="nb">export</span> <span class="nv">ZULIP_API_KEY</span><span class="o">=</span>BOT_API_KEY
|
||||
</pre></div>
|
||||
<p>The parameters specified in environment variables would override the parameters provided in the config file. For example, if you specify the variable <code>key</code> in the config file and specify <code>ZULIP_API_KEY</code> as an environment variable, the value of <code>ZULIP_API_KEY</code> would be considered.</p>
|
||||
<p>The following variables can be specified:
|
||||
<br/> 1. <code>ZULIP_CONFIG</code>
|
||||
<br/> 2. <code>ZULIP_API_KEY</code>
|
||||
<br/> 3. <code>ZULIP_EMAIL</code>
|
||||
<br/> 4. <code>ZULIP_SITE</code>
|
||||
<br/> 5. <code>ZULIP_CERT</code>
|
||||
<br/> 6. <code>ZULIP_CERT_KEY</code>
|
||||
<br/> 7. <code>ZULIP_CERT_BUNDLE</code>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
{% endblock %}
|
||||
|
|
@ -5,7 +5,7 @@
|
|||
{% block portico_content %}
|
||||
<div class="app help api-docs terms-page inline-block">
|
||||
<div class="sidebar">
|
||||
<h1 class="no-arrow"><a href="/api-new/" class="no-underline">Index</a></h1>
|
||||
<h1 class="no-arrow"><a href="/api/" class="no-underline">Index</a></h1>
|
||||
{{ render_markdown_path("zerver/api/sidebar.md") }}
|
||||
</div>
|
||||
|
||||
|
|
@ -19,7 +19,7 @@
|
|||
<div id="footer" class="documentation-footer">
|
||||
<hr />
|
||||
<p>
|
||||
<a href="/api-new/">Documentation home</a>.
|
||||
<a href="/api/">Documentation home</a>.
|
||||
The Zulip software, including this documentation, is open source! Learn how
|
||||
you can contribute <a href="https://zulip.readthedocs.io/en/latest/user-docs.html">here</a>.
|
||||
</p>
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
## REST API
|
||||
|
||||
* [Installation instructions](/api-new/installation-instructions)
|
||||
* [API keys](/api-new/api-keys)
|
||||
* [Usage](/api-new/usage)
|
||||
* [Installation instructions](/api/installation-instructions)
|
||||
* [API keys](/api/api-keys)
|
||||
* [Usage](/api/usage)
|
||||
|
||||
## Integrations
|
||||
|
||||
|
|
|
|||
|
|
@ -53,10 +53,9 @@ class DocPageTest(ZulipTestCase):
|
|||
# type: () -> None
|
||||
self._test('/api/', 'We hear you like APIs')
|
||||
self._test('/api/endpoints/', 'pre-built API bindings for')
|
||||
self._test('/api-new/', 'We hear you like APIs')
|
||||
self._test('/api-new/api-keys', 'you can use its email and API key')
|
||||
self._test('/api-new/installation-instructions', 'No download required!')
|
||||
self._test('/api-new/usage', 'steal away your hearts')
|
||||
self._test('/api/api-keys', 'you can use its email and API key')
|
||||
self._test('/api/installation-instructions', 'No download required!')
|
||||
self._test('/api/usage', 'steal away your hearts')
|
||||
self._test('/team/', 'industry veterans')
|
||||
self._test('/history/', 'Cambridge, Massachusetts')
|
||||
# Test the i18n version of one of these pages.
|
||||
|
|
|
|||
|
|
@ -431,7 +431,7 @@ i18n_urls = [
|
|||
name='zerver.views.registration.accounts_home_from_multiuse_invite'),
|
||||
|
||||
# API and integrations documentation
|
||||
url(r'^api/$', APIView.as_view(template_name='zerver/api.html')),
|
||||
|
||||
url(r'^api/endpoints/$', zerver.views.integrations.api_endpoint_docs,
|
||||
name='zerver.views.integrations.api_endpoint_docs'),
|
||||
url(r'^integrations/doc-html/(?P<integration_name>[^/]*)$',
|
||||
|
|
@ -561,7 +561,7 @@ urls += [url(r'^', include('social_django.urls', namespace='social'))]
|
|||
urls += [url(r'^help/(?P<article>.*)$',
|
||||
MarkdownDirectoryView.as_view(template_name='zerver/help/main.html',
|
||||
path_template='/zerver/help/%s.md'))]
|
||||
urls += [url(r'^api-new/(?P<article>[-\w]*\/?)$',
|
||||
urls += [url(r'^api/(?P<article>[-\w]*\/?)$',
|
||||
MarkdownDirectoryView.as_view(template_name='zerver/api/main.html',
|
||||
path_template='/zerver/api/%s.md'))]
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue