Merge pull request #236 from matrix-org/rav/search_spec_fixes

Tweaks/clarifications to search spec

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
+                                  Token that can be used to get the next batch
-                                  batch of results in the group, if exists.
+                                  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: |-
                {

specification/modules/search.rst

@@ -10,6 +10,8 @@ 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
@@ -36,9 +38,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 value of ``count`` gives an approximation of the total number of
-the search query matching 1000s of results and the server truncating the
+results. Homeservers may give an estimate rather than an exact value for this
-response.
+field.
 
 Ordering
 --------
@@ -84,7 +86,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