api docs: Document GET /messages/matches_narrow endpoint.

With extensive tweaks from tabbott to provide clear explanations for
the features.

templates/zerver/api/check-narrow-matches.md

@@ -0,0 +1,32 @@
+# Check messages match narrow
+
+{generate_api_description(/messages/matches_narrow:get)}
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/messages/matches_narrow:get|example}
+
+{tab|curl}
+
+{generate_code_example(curl)|/messages/matches_narrow:get|example}
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/messages/matches_narrow:get}
+
+## Response
+
+#### Return values
+
+{generate_return_values_table|zulip.yaml|/messages/matches_narrow:get}
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/messages/matches_narrow:get|fixture(200)}

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

@@ -10,6 +10,7 @@
 * [Remove an emoji reaction](/api/remove-reaction)
 * [Render a message](/api/render-message)
 * [Get a message's raw markdown](/api/get-raw-message)
+* [Check messages match narrow](/api/check-narrow-matches)
 * [Get a message's edit history](/api/get-message-history)
 * [Update personal message flags](/api/update-message-flags)
 * [Mark messages as read in bulk](/api/mark-all-as-read)

zerver/openapi/python_examples.py

@@ -583,6 +583,37 @@ def get_messages(client: Client) -> None:
     validate_against_openapi_schema(result, '/messages', 'get', '200')
     assert len(result['messages']) <= request['num_before']
 
+@openapi_test_function("/messages/matches_narrow:get")
+def check_messages_match_narrow(client: Client) -> None:
+    message = {
+        "type": "stream",
+        "to": "Verona",
+        "topic": "test_topic",
+        "content": "http://foo.com"
+    }
+    msg_ids = []
+    response = client.send_message(message)
+    msg_ids.append(response['id'])
+    message['content'] = "no link here"
+    response = client.send_message(message)
+    msg_ids.append(response['id'])
+
+    # {code_example|start}
+    # Check which messages within an array match a narrow.
+    request = {
+        'msg_ids': msg_ids,
+        'narrow': [{'operator': 'has', 'operand': 'link'}],
+    }
+
+    result = client.call_endpoint(
+        url='messages/matches_narrow',
+        method='GET',
+        request=request
+    )
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/messages/matches_narrow', 'get', '200')
+
 @openapi_test_function("/messages/{message_id}:get")
 def get_raw_message(client: Client, message_id: int) -> None:
 
@@ -1117,6 +1148,7 @@ def test_messages(client: Client, nonadmin_client: Client) -> None:
     update_message(client, message_id)
     get_raw_message(client, message_id)
     get_messages(client)
+    check_messages_match_narrow(client)
     get_message_history(client, message_id)
     delete_message(client, message_id)
     mark_all_as_read(client)

zerver/openapi/zulip.yaml

@@ -1342,6 +1342,91 @@ paths:
                         "msg": "Invalid message(s)",
                         "code": "BAD_REQUEST"
                     }
+  /messages/matches_narrow:
+    get:
+      operationId: check_messages_match_narrow
+      tags: ["messages"]
+      description: |
+        Check whether a set of messages match a [narrow](/api/construct-narrow).
+
+        `GET {{ api_url }}/v1/messages/matches_narrow`
+
+        For many common narrows (E.g. a topic), clients can write an
+        efficient client-side check to determine whether a
+        newly arrived message belongs in the view.
+
+        This endpoint is designed to allow clients to handle more complex narrows
+        for which the client does not (or in the case of full-text search,
+        cannot) implement this check.
+
+        The format of the `match_subject` and `match_content` objects is designed to match
+        those of `GET /messages`, so that a client can splice these fields into a
+        `message` object received from `GET /events` and end up with an extended message
+        object identical to how a `GET /messages` for the current narrow would have
+        returned the message.
+      parameters:
+      - name: msg_ids
+        in: query
+        description: List of IDs for the messages to check.
+        schema:
+          type: array
+          items:
+            type: integer
+        example: [31, 32]
+        required: true
+      - name: narrow
+        in: query
+        description: A structure defining the narrow to check against. See how to
+          [construct a narrow](/api/construct-narrow).
+        schema:
+          type: array
+          items:
+            type: object
+        example: [{'operator': 'has', 'operand': 'link'}]
+        required: true
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    messages:
+                      type: object
+                      description: |
+                        A dictionary with a key for each queried message that matches the narrow,
+                        with message IDs as keys and search rendering data as values.
+                      additionalProperties:
+                        type: object
+                        properties:
+                          match_content:
+                            type: string
+                            description: |
+                              HTML content of a queried message that matches the narrow.  If the
+                              narrow is a search narrow, `<span class="highlight">` elements
+                              will be included, wrapping the matches for the search keywords.
+                          match_subject:
+                            type: string
+                            description: |
+                              HTML-escaped topic of a queried message that matches the narrow.  If the
+                              narrow is a search narrow, `<span class="highlight">` elements
+                              will be included wrapping the matches for the search keywords.
+                        description: |
+                          The ID of the message that matches the narrow.  No record will be returned
+                          for queried messages that do not match the narrow.
+                - example:
+                    {
+                      'result': 'success',
+                      'msg': '',
+                      'messages': {
+                        '31': {
+                          'match_content': '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
+                          'match_subject': 'test_topic'
+                        }
+                      }
+                    }
   /user_uploads:
     post:
       operationId: upload_file

zerver/tests/test_openapi.py

@@ -197,7 +197,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
     checked_endpoints: Set[str] = set()
     pending_endpoints = {
         #### TODO: These endpoints are a priority to document:
-        '/messages/matches_narrow',
         '/realm/presence',
         '/streams/{stream_id}/members',
         '/streams/{stream_id}/delete_topic',