mirror of https://github.com/zulip/zulip.git
api docs: Remove old and outdated endpoint docs.
This commit is contained in:
Eeshan Garg
showell
parent
1fd71287d6
commit
479bc41ca5
|
|
@ -1,6 +1,6 @@
|
|||
# We hear you like APIs...
|
||||
|
||||
We have a [well-documented API](/api/endpoints) that allows you to build
|
||||
We have a [well-documented API](/api) that allows you to build
|
||||
custom integrations, in addition to our [existing integrations](/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
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ zulip-send hamlet@example.com \
|
|||
|
||||
You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file.
|
||||
|
||||
See also the [full API endpoint documentation](/api/endpoints).
|
||||
See also the [full API endpoint documentation](/api).
|
||||
</div>
|
||||
|
||||
<div data-language="javascript" markdown="1">
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ zulip-send --stream Denmark --subject Castle \
|
|||
|
||||
You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file.
|
||||
|
||||
See also the [full API endpoint documentation](/api/endpoints).
|
||||
See also the [full API endpoint documentation](/api).
|
||||
</div>
|
||||
|
||||
<div data-language="javascript" markdown="1">
|
||||
|
|
|
|||
|
|
@ -1,146 +0,0 @@
|
|||
[
|
||||
{
|
||||
"method": "POST",
|
||||
"endpoint": "messages",
|
||||
"example_response": "{'msg': '', 'result': 'success', 'id': 12345678}",
|
||||
"returns": [
|
||||
[
|
||||
"id",
|
||||
"The ID of the newly created message."
|
||||
]
|
||||
],
|
||||
"call": "Send a message",
|
||||
"arguments": [
|
||||
[
|
||||
"type",
|
||||
"One of {private, stream}"
|
||||
],
|
||||
[
|
||||
"content",
|
||||
"The content of the message. Maximum message size of 10000 bytes."
|
||||
],
|
||||
[
|
||||
"to",
|
||||
"In the case of a stream message, a string identifying the stream. In the case of a private message, a JSON-encoded list containing the usernames of the recipients."
|
||||
],
|
||||
[
|
||||
"subject",
|
||||
"The topic for the message (Only required if type is \u201cstream\u201d). Maximum length of 60 characters."
|
||||
]
|
||||
],
|
||||
"example_request": {
|
||||
"python": "<div class=\"codehilite\"><pre>\n<span class=\"n\">client</span><span class=\"o\">.</span><span class=\"n\">send_message</span><span class=\"p\">({</span>\n <span class=\"s\">\"type\"</span><span class=\"p\">:</span> <span class=\"s\">\"private\"</span><span class=\"p\">,</span>\n <span class=\"s\">\"to\"</span><span class=\"p\">:</span> <span class=\"s\">\"wdaher@example.com\"</span><span class=\"p\">,</span>\n <span class=\"s\">\"content\"</span><span class=\"p\">:</span> <span class=\"s\">\"I come not, friends, to steal away your hearts.\"</span>\n<span class=\"p\">}</span>)\n<span class=\"n\">client</span><span class=\"o\">.</span><span class=\"n\">send_message</span><span class=\"p\">(</span><span class=\"n\"><span class=\"p\">{</span>\n <span class=\"s\">\"type\"</span><span class=\"p\">:</span> <span class=\"s\">\"stream\"</span><span class=\"p\">,</span>\n <span class=\"s\">\"to\"</span><span class=\"p\">:</span> <span class=\"s\">\"Denmark\"</span><span class=\"p\">,</span>\n <span class=\"s\">\"subject\"</span><span class=\"p\">:</span> <span class=\"s\">\"Castle\"</span><span class=\"p\">,</span>\n <span class=\"s\">\"content\"</span><span class=\"p\">:</span> <span class=\"s\">\"Something is rotten in the state of Denmark.\"</span>\n<span class=\"p\">}</span></span><span class=\"p\">)</span>\n</pre></div>\n",
|
||||
"curl": "<h5>Stream message</h5>\n<div class=\"codehilite\"><pre>curl https://zulip.example.com/api/v1/messages <span class=\"se\">\\</span>\n -u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"type=stream\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"to=Denmark\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"subject=Castle\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"content=Something is rotten in the state of Denmark.\"</span>\n</pre></div>\n<h5>Private message</h5>\n<div class=\"codehilite\"><pre>curl https://zulip.example.com/api/v1/messages <span class=\"se\">\\</span>\n -u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"type=private\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"to=othello@example.com\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"content=I come not, friends, to steal away your hearts.\"</span>\n</pre></div>"
|
||||
}
|
||||
},
|
||||
{
|
||||
"method": "POST",
|
||||
"endpoint": "register",
|
||||
"example_response": "{'msg': '', 'last_event_id': -1, 'result': 'success', 'queue_id': '1375801870:2942'}",
|
||||
"returns": [
|
||||
[
|
||||
"queue_id",
|
||||
"The ID of the queue that has been allocated for your client"
|
||||
],
|
||||
[
|
||||
"last_event_id",
|
||||
"The initial value of the `last_event_id` value for to pass to `GET /api/v1/events`."
|
||||
]
|
||||
],
|
||||
"call": "Register a queue to receive new messages",
|
||||
"arguments": [
|
||||
[
|
||||
"event_types",
|
||||
"(optional) A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: <ul><li><strong>message</strong> (messages),</li> <li><strong>subscriptions</strong> (changes in your subscriptions),</li> <li><strong>realm_user</strong> (changes in the list of users in your realm), and</li> <li><strong>pointer</strong> (changes in your pointer).</li></ul>\n If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: <strong>event_types=[\"message\"]</strong>"
|
||||
],
|
||||
[
|
||||
"apply_markdown",
|
||||
"(optional) set to \u201ctrue\u201d if you would like the content to be rendered in HTML format (by default, the API returns the raw text that the user entered)"
|
||||
]
|
||||
],
|
||||
"example_request": {
|
||||
"python": "<div class=\"codehilite\"><pre><span class=\"n\">client</span><span class=\"o\">.</span><span class=\"n\">register<span class=\"p\">()</span>\n</span></pre></div>",
|
||||
"curl": "<div class=\"codehilite\"><pre>curl https://zulip.example.com/api/v1/register <span class=\"se\">\\</span>\n -u othello-bot@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 <span class=\"se\">\\</span>\n -d <span class=\"s2\">'event_types=[\"message\"]'</span>\n</pre></div>"
|
||||
}
|
||||
},
|
||||
{
|
||||
"method": "GET",
|
||||
"endpoint": "events",
|
||||
"example_response":
|
||||
"{'result': 'success',
|
||||
'msg': '',
|
||||
'events': [
|
||||
{'type': 'message',
|
||||
'id': 0,
|
||||
'message': {
|
||||
'content_type': 'text/x-markdown',
|
||||
'avatar_url': 'https://url/for/othello-bots/avatar',
|
||||
'timestamp': 1375978403,
|
||||
'display_recipient': 'Denmark',
|
||||
'sender_id': 13215,
|
||||
'sender_full_name': 'Othello Bot',
|
||||
'sender_email': 'othello-bot@example.com',
|
||||
'sender_short_name': 'othello-bot',
|
||||
'sender_realm_str': 'example',
|
||||
'content': 'Something is rotten in the state of Denmark.',
|
||||
'recipient_id': 12314,
|
||||
'client': 'website',
|
||||
'subject_links': [],
|
||||
'subject': 'Castle',
|
||||
'type': 'stream',
|
||||
'id': 12345678,
|
||||
}
|
||||
},
|
||||
{'type': 'message',
|
||||
'id': 1,
|
||||
'message': {
|
||||
'content_type': 'text/x-markdown',
|
||||
'avatar_url': 'https://url/for/othello-bots/avatar',
|
||||
'timestamp': 1375978404,
|
||||
'display_recipient': [{'full_name': 'Hamlet of Denmark',
|
||||
'email': 'hamlet@example.com',
|
||||
'short_name': 'hamlet',
|
||||
'id': 31572}],
|
||||
'sender_id': 13215,
|
||||
'sender_full_name': 'Othello Bot',
|
||||
'sender_email': 'othello-bot@example.com',
|
||||
'sender_short_name': 'othello-bot',
|
||||
'sender_realm_str': 'example',
|
||||
'content': 'I come not, friends, to steal away your hearts.',
|
||||
'recipient_id': 18391,
|
||||
'client': 'website',
|
||||
'subject_links': [],
|
||||
'subject': '',
|
||||
'type': 'private',
|
||||
'id': 12345679,
|
||||
}
|
||||
}
|
||||
]
|
||||
}",
|
||||
"returns": [
|
||||
[
|
||||
"events",
|
||||
"an array (possibly zero-length if dont_block is set) of events with IDs newer than `last_event_id`. Event IDs are guaranted to be increasing, but they are not guaranteed to be consecutive."
|
||||
]
|
||||
],
|
||||
"call": "Get new events from an events queue",
|
||||
"arguments": [
|
||||
[
|
||||
"queue_id",
|
||||
"The ID of a queue that you registered via <code>POST /api/v1/register</code>"
|
||||
],
|
||||
[
|
||||
"last_event_id",
|
||||
"The highest event ID in this queue that you've received and wish to acknowledge. See the code for <tt>call_on_each_event</tt> in the <tt>zulip</tt> Python module for an example implementation of correctly processing each event exactly once."
|
||||
],
|
||||
[
|
||||
"dont_block",
|
||||
"(optional) set to \u201ctrue\u201d if the client is requesting a nonblocking reply. If not specified, the request will block until either a new event is available or a few minutes have passed, in which case the server will send the client a heartbeat event."
|
||||
]
|
||||
],
|
||||
"example_request": {
|
||||
"python": "<div class=\"codehilite\"><pre><span class=\"n\">client</span><span class=\"o\">.</span><span class=\"n\">get_events<span class=\"p\">()</span>\n</span></pre></div> or if you want the event queues managed for you, <div class=\"codehilite\"><pre><span class=\"n\">client</span><span class=\"o\">.</span><span class=\"n\">call_on_each_event<span class=\"p\">()</span>\n</span></pre></div>",
|
||||
"curl": "<div class=\"codehilite\"><pre>curl -G https://zulip.example.com/api/v1/events <span class=\"se\">\\</span>\n -u othello-bot@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"queue_id=1375801870:2942\"</span> <span class=\"se\">\\</span>\n -d <span class=\"s2\">\"last_event_id=-1\"</span>\n</pre></div>"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
{% extends "zerver/portico.html" %}
|
||||
|
||||
{# API information page #}
|
||||
|
||||
{% block customhead %}
|
||||
{{ super() }}
|
||||
{% endblock %}
|
||||
|
||||
{% block portico_content %}
|
||||
<h1 class="api-page-header">API endpoints documentation</h1>
|
||||
|
||||
<p>In addition to our <a href="/api">pre-built API bindings for
|
||||
Python</a>, we also have
|
||||
a <a href="http://en.wikipedia.org/wiki/Representational_state_transfer">REST-ful</a>
|
||||
web API.</p>
|
||||
|
||||
<ul class="nav nav-tabs" id="api-example-tabs">
|
||||
<li class="active"><a href="#curl" data-toggle="tab" data-class="curl">curl</a></li>
|
||||
<li><a href="#python" data-toggle="tab" data-class="python">Python</a></li>
|
||||
</ul>
|
||||
|
||||
{% autoescape off %}
|
||||
{% for blurb in content %}
|
||||
<div class="api-block">
|
||||
<h2 class="call">{{ blurb.call }}</h2>
|
||||
<div class="endpoint"><code>{{blurb.method}} {{ blurb.endpoint }}</code></div>
|
||||
<div class="api-details">
|
||||
<h3>Arguments</h3>
|
||||
<dl class="dl-horizontal arguments">
|
||||
{% for argument in blurb.arguments %}
|
||||
<dt><code>{{ argument.0 }}</code></dt>
|
||||
<dd>{{ argument.1 }}</dd>
|
||||
{% endfor %}
|
||||
</dl>
|
||||
|
||||
<h3>Return values</h3>
|
||||
<dl class="dl-horizontal returns">
|
||||
{% for return in blurb.returns %}
|
||||
<dt><code>{{ return.0 }}</code></dt>
|
||||
<dd>{{ return.1 }}</dd>
|
||||
{% endfor %}
|
||||
</dl>
|
||||
|
||||
{% if blurb.example_request %}
|
||||
<h3>Example request</h3>
|
||||
{% for lang, req in blurb.example_request.items() %}
|
||||
<div class="example_request {{ lang }}">
|
||||
{{ req }}
|
||||
</div>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% if blurb.rendered_response %}
|
||||
<h3>Example response</h3>
|
||||
<div class="example_response">
|
||||
{{ blurb.rendered_response }}
|
||||
</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
{% endautoescape %}
|
||||
<script>
|
||||
$('a[data-toggle="tab"]').on('shown', function (e) {
|
||||
$("." + $(e.target).data("class")).show();
|
||||
$("." + $(e.relatedTarget).data("class")).hide();
|
||||
});
|
||||
</script>
|
||||
{% endblock %}
|
||||
|
|
@ -52,7 +52,6 @@ class DocPageTest(ZulipTestCase):
|
|||
@slow("Tests dozens of endpoints, including generating lots of emails")
|
||||
def test_doc_endpoints(self) -> None:
|
||||
self._test('/api/', 'We hear you like APIs')
|
||||
self._test('/api/endpoints/', 'pre-built API bindings for')
|
||||
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')
|
||||
|
|
|
|||
|
|
@ -152,33 +152,3 @@ def integration_doc(request: HttpRequest, integration_name: str=REQ(default=None
|
|||
doc_html_str = render_markdown_path(integration.doc, context)
|
||||
|
||||
return HttpResponse(doc_html_str)
|
||||
|
||||
def api_endpoint_docs(request: HttpRequest) -> HttpResponse:
|
||||
context = {} # type: Dict[str, Any]
|
||||
add_api_uri_context(context, request)
|
||||
|
||||
raw_calls = open('templates/zerver/api_content.json', 'r').read()
|
||||
calls = ujson.loads(raw_calls)
|
||||
langs = set()
|
||||
for call in calls:
|
||||
call["endpoint"] = "%s/v1/%s" % (
|
||||
context["api_url"],
|
||||
call["endpoint"])
|
||||
call["example_request"]["curl"] = call["example_request"]["curl"].replace(
|
||||
"https://api.zulip.com",
|
||||
context["api_url"])
|
||||
response = call['example_response']
|
||||
if '\n' not in response:
|
||||
# For 1-line responses, pretty-print them
|
||||
extended_response = response.replace(", ", ",\n ")
|
||||
else:
|
||||
extended_response = response
|
||||
call['rendered_response'] = bugdown.convert("~~~ .py\n" + extended_response + "\n~~~\n")
|
||||
for example_type in ('request', 'response'):
|
||||
for lang in call.get('example_' + example_type, []):
|
||||
langs.add(lang)
|
||||
return render(
|
||||
request,
|
||||
'zerver/api_endpoints.html',
|
||||
context={'content': calls, 'langs': langs},
|
||||
)
|
||||
|
|
|
|||
|
|
@ -447,9 +447,6 @@ i18n_urls = [
|
|||
name='zerver.views.registration.accounts_home_from_multiuse_invite'),
|
||||
|
||||
# API and integrations documentation
|
||||
|
||||
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>[^/]*)$',
|
||||
zerver.views.integrations.integration_doc,
|
||||
name="zerver.views.integrations.integration_doc"),
|
||||
|
|
|
|||
Loading…
Reference in New Issue