/api: Clean up the API documentation homepage.

templates/zerver/api/index.md

@@ -1,12 +1,22 @@
-# We hear you like APIs...
+# The Zulip API
 
-We have a [well-documented API](/api) that allows you to build
+Zulip's APIs allow you to integrate other services with Zulip.  This
-custom integrations, in addition to our [existing integrations](/integrations).
+guide should help you find the API you need:
-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](https://github.com/zulip/zulip-js) 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](/integrations).
+* First, check if the tool you'd like to integrate with Zulip
+[already has a native integration](/integrations).
+* Next, check if [Zapier](https://zapier.com/apps) or
+  [IFTTT](https://ifttt.com/search/services) 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/integration-guide#webhook-integrations)
+  or use [Zulip's API for sending messages](/api/stream-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
+  [Zulip's real-time events API](/api/get-events-from-queue).
+* If you'd like to do something else, check out the full
+  [REST API](/api/rest), generally starting with
+  [installing the API client bindings](/api/installation-instructions).
 
-{{ render_markdown_path("zerver/api/sidebar.md") }}

templates/zerver/api/main.html

@@ -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/" class="no-underline">Index</a></h1>
+        <h1 class="no-arrow"><a href="/api/" class="no-underline">Home</a></h1>
         {{ render_markdown_path("zerver/api/sidebar.md", api_uri_context) }}
         <h1 class="home-link"><a href="/" class="no-underline">Back to Home</a></h1>
     </div>

templates/zerver/api/sidebar.md

@@ -9,7 +9,7 @@
 * [Walkthrough](/api/webhook-walkthrough)
 * [Documenting integrations](/api/integration-docs-guide)
 
-## Interactive bots (experimental)
+## Interactive bots (beta)
 
 * [Running bots](/api/running-bots)
 * [Writing bots](/api/writing-bots)