From b7c255a887de1166c88ce27f6b73710a9616ad17 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Thu, 17 Dec 2015 13:40:22 +0000
Subject: [PATCH 1/2] Tweaks/clarifications to search spec

Fixes https://matrix.org/jira/browse/SPEC-305
---
 api/client-server/search.yaml    | 20 ++++++++++++++++----
 specification/modules/search.rst | 10 ++++------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 0bf7ffd9..0ddbfe0a 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -20,12 +20,19 @@ securityDefinitions:
 paths:
   "/search":
     post:
-      summary: Search server side for things.
+      summary: Perform a server-side search.
       description: |-
         Performs a full text search across different categories.
       security:
         - accessToken: []
       parameters:
+        - in: query
+          name: next_batch
+          type: string
+          description: |-
+            The point to return events from. If given, this should be a
+            `next_batch` result from a previous call to this endpoint.
+          x-example: "YWxsCgpOb25lLDM1ODcwOA"
         - in: body
           name: body
           schema:
@@ -260,8 +267,11 @@ paths:
                                 type: string
                                 title: Next Batch in Group
                                 description: |-
-                                  Token that can be used to get the next
-                                  batch of results in the group, if exists.
+                                  Token that can be used to get the next batch
+                                  of results in the group, by passing as the
+                                  `next_batch` parameter to the next call. If
+                                  this field is absent, there are no more
+                                  results in this group.
                               order:
                                 type: integer
                                 title: Group Order
@@ -280,7 +290,9 @@ paths:
                         title: Next Batch
                         description: |-
                           Token that can be used to get the next batch of
-                          results, if exists.
+                          results, by passing as the `next_batch` parameter to
+                          the next call. If this field is absent, there are no
+                          more results.
           examples:
             application/json: |-
                {
diff --git a/specification/modules/search.rst b/specification/modules/search.rst
index f795e18a..def21877 100644
--- a/specification/modules/search.rst
+++ b/specification/modules/search.rst
@@ -8,8 +8,6 @@ rooms that the user has been in, including those that they have left. Only
 events that the user is allowed to see will be searched, e.g. it won't include
 events in rooms that happened after you left.
 
-Client behaviour
-----------------
 {{search_http_api}}
 
 Search Categories
@@ -36,9 +34,9 @@ The search will *not* include rooms that are end to end encrypted.
 The results include a ``rank`` key that can be used to sort the results by
 relevancy. The higher the ``rank`` the more relevant the result is.
 
-The value of ``count`` may not match the number of results. For example due to
-the search query matching 1000s of results and the server truncating the
-response.
+The value of ``count`` gives an approximation of the total number of
+results. Homeservers may give an estimate rather than an exact value for this
+field.
 
 Ordering
 --------
@@ -84,7 +82,7 @@ The currently supported locations for the ``next_batch`` token are:
 - ``search_categories.<category>.groups.<group_key>.<group_id>.next_batch``
 
 A server need not support pagination, even if there are more matching results.
-In which case they must not return a ``next_batch`` token in the response.
+In that case, they must not return a ``next_batch`` token in the response.
 
 
 Security considerations

From e4dd346a81c0dd9648637e0df461d882e5c2bf88 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Thu, 17 Dec 2015 14:07:35 +0000
Subject: [PATCH 2/2] Restore 'client behaviour' section

Because it's the standard
---
 specification/modules/search.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/specification/modules/search.rst b/specification/modules/search.rst
index def21877..bb8f0141 100644
--- a/specification/modules/search.rst
+++ b/specification/modules/search.rst
@@ -8,6 +8,10 @@ rooms that the user has been in, including those that they have left. Only
 events that the user is allowed to see will be searched, e.g. it won't include
 events in rooms that happened after you left.
 
+Client behaviour
+----------------
+There is a single HTTP API for performing server-side search, documented below.
+
 {{search_http_api}}
 
 Search Categories