From e42c8b5b63a637eae7863285f342938fad6adc18 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Wed, 14 Oct 2015 14:19:11 +0100
Subject: [PATCH] Add search API

---
 api/client-server/v1/search.yaml | 126 +++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 api/client-server/v1/search.yaml

diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml
new file mode 100644
index 00000000..c9e9b14b
--- /dev/null
+++ b/api/client-server/v1/search.yaml
@@ -0,0 +1,126 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Search API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/search":
+    post:
+      summary: Search server side for things.
+      description: |-
+        Performs a full text search across different categories.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "search_categories": {
+                  "room_events": {
+                    "keys": [
+                      "content.body"
+                    ],
+                    "search_term": "martians and men"
+                  }
+                }
+              }
+            properties:
+              search_categories:
+                type: object
+                description: Describes which categories to search in and
+                  their creteria.
+                properties:
+                  room_events:
+                    type: object
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      search_term:
+                        type: string
+                        description: The string to search events for
+                      keys:
+                        type: array
+                        items:
+                          type: string
+                          enum: ["content.body", "content.name", "content.topic"]
+                        description: The keys to search. Defaults to all.
+                    required: ["search_term"]
+            required: ["search_categories"]
+      responses:
+        200:
+          description: Results of the search.
+          schema:
+            type: object
+            required: ["search_categories"]
+            properties:
+              search_categories:
+                type: object
+                description: Describes which categories to search in and
+                  their creteria.
+                properties:
+                  room_events:
+                    type: object
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      count:
+                        type: number
+                        description: Total number of results found
+                      results:
+                        type: object
+                        description: Mapping of event_id to result.
+                        additionalProperties:
+                          type: object
+                          desciption: The result object.
+                          properties:
+                            rank:
+                              type: number
+                              description: A number that describes how closely
+                                this result matches the search. Higher is
+                                closer.
+                            result:
+                                type: object
+                                description: The event that matched.
+                                allOf:
+                                  - "$ref": "core-event-schema/room_event.json"
+          examples:
+            application/json: |-
+               {
+                  "search_categories": {
+                    "room_events": {
+                      "count": 24,
+                      "results": {
+                        "$144429830826TWwbB:localhost": {
+                          "rank": 0.00424866,
+                          "result": {
+                            "age": 526228296,
+                            "content": {
+                              "body": "Test content",
+                              "msgtype": "m.text"
+                            },
+                            "event_id": "$144429830826TWwbB:localhost",
+                            "origin_server_ts": 1444298308034,
+                            "room_id": "!qPewotXpIctQySfjSy:localhost",
+                            "type": "m.room.message",
+                            "user_id": "@test:localhost"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }