api docs: Add guide for creating narrows.

Dramatically edited by tabbott to simplify the discussion and
duplication of content in our main search documentation.

templates/zerver/api/construct-narrow.md

@@ -0,0 +1,40 @@
+# Construct a narrow
+
+A **narrow** is a set of filters for Zulip messages, that can be based
+on many different factors (like sender, stream, topic, search
+keywords, etc.).  the Zulip API (espec in the API for fetching messages).
+
+It is simplest top explain the algorithm for encoding a search as a
+narrow using a single example.  Consider the following search query
+(written as it would be entered in the Zulip webapp's search box).  It
+filters for messages sent on stream `announce`, not sent by
+`iago@zulip.com`, and containing the phrase `cool sunglasses`:
+
+```
+stream:announce -sender:iago@zulip.com cool sunglasses
+```
+
+This query would be JSON-encoded for use in the Zulip API using JSON
+as a list of simple objects, as follows:
+
+```
+[
+    {
+        "operator": "stream",
+        "operand": "announce"
+    },
+    {
+        "operator": "sender",
+        "operand": "iago@zulip.com",
+        "negated": true
+    },
+    {
+        "operator": "search",
+        "operand": "cool sunglasses"
+    }
+]
+```
+
+The full set of search/narrowing options supported by the Zulip API is
+documented in
+[the Zulip Help Center article on search](/help/search-for-messages).

templates/zerver/help/include/rest-endpoints.md

@@ -4,6 +4,7 @@
 * [Update a message](/api/update-message)
 * [Render a message](/api/render-message)
 * [Upload a file](/api/upload-file)
+* [Construct a narrow](/api/construct-narrow)
 
 #### Streams