Document the v2 filter GET API

api/client-server/v2_alpha/definitions/definitions

@@ -0,0 +1 @@
+.

api/client-server/v2_alpha/definitions/event_filter.json

@@ -0,0 +1,53 @@
+{
+  "type": "object",
+  "properties": {
+    "types": {
+      "type": "array",
+      "description":
+        "A list of event types to include. If this list is absent then all event types are included.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "not_types": {
+      "type": "array",
+      "description":
+        "A list of event types to exclude. If this list is absent then no event types are excluded.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "senders": {
+      "type": "array",
+      "description":
+        "A list of senders IDs to include. If this list is absent then all senders are included.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "not_senders": {
+      "type": "array",
+      "description":
+        "A list of sender IDs to exclude. If this list is absent then no senders are excluded.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "rooms": {
+      "type": "array",
+      "description":
+        "A list of room IDs to include. If this list is absent then all rooms are included.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "not_rooms": {
+      "type": "array",
+      "description":
+        "A list of room IDs to exclude. If this list is absent then no rooms are excluded.",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

api/client-server/v2_alpha/definitions/sync_filter.json

@@ -0,0 +1,48 @@
+{
+  "type": "object",
+  "properties": {
+    "room": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "description":
+            "The state events to include for rooms.",
+          "allOf": [{"$ref": "definitions/event_filter.json"}]
+        },
+        "events": {
+          "description":
+            "The message and state update events to include for rooms.",
+          "allOf": [{"$ref": "definitions/event_filter.json"}]
+        },
+        "ephemeral": {
+          "description":
+            "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.",
+          "allOf": [{"$ref": "definitions/event_filter.json"}]
+        }
+      }
+    },
+    "public_user_data": {
+      "description":
+        "The public user data, e.g. profile and presence, to include.",
+      "allOf": [{"$ref": "definitions/event_filter.json"}]
+    },
+    "private_user_data": {
+      "description":
+        "Events that are private to a user but shared amoungst their devices, e.g. notification settings, to include.",
+      "allOf": [{"$ref": "definitions/event_filter.json"}]
+    },
+    "event_format": {
+      "description":
+        "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
+      "type": "string"
+    },
+    "event_fields": {
+      "type": "array",
+      "description":
+        "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A server may include more fields than were requested.",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

api/client-server/v2_alpha/filter.yaml

@@ -16,103 +16,10 @@ securityDefinitions:
     description: The user_id or application service access_token
     name: access_token
     in: query
-definitions:
-  EventFilter:
-    title:
-    type: object
-    properties:
-      types:
-        type: array
-        description: |-
-          A list of event types to include.
-          If this list is absent then all event types are included.
-        items:
-          type: string
-      not_types:
-        type: array
-        description: |-
-          A list of event types to exclude.
-          If this list is absent then no event types are excluded.
-        items:
-          type: string
-      senders:
-        type: array
-        description: |-
-          A list of senders IDs to include.
-          If this list is absent then all senders are included.
-        items:
-          type: string
-      not_senders:
-        type: array
-        description: |-
-          A list of sender IDs to exclude
-          If this list is absent then no senders are excluded.
-        items:
-          type: string
-      rooms:
-        type: array
-        description: |-
-          A list of room IDs to include.
-          If this list is absent then all rooms are included.
-        items:
-          type: string
-      not_rooms:
-        type: array
-        description: |-
-          A list of room IDs to exclude
-          If this list is absent then no rooms are excluded.
-        items:
-          type: string
-  SyncFilter:
-    room:
-      type: object
-      properties:
-        state:
-          description:
-            The state events to include for rooms.
-          allOf:
-          - $ref: "#/definitions/EventFilter"
-        events:
-          description:
-            The message and state update events to include for rooms.
-          allOf:
-          - $ref: "#/definitions/EventFilter"
-        ephemeral:
-          description: |-
-            The events that aren't recorded in the permenant history, e.g.
-            typing and receipts, to include for rooms.
-          allOf:
-          - $ref: "#/definitions/EventFilter"
-    public_user_data:
-      description: |-
-        The public user data, e.g. profile and presence, to include.
-      allOf:
-          - $ref: "#/definitions/EventFilter"
-    private_user_data:
-      description: |-
-        Events that are private to a user but shared amoungst their devices,
-        e.g. notification settings, to include.
-      allOf:
-          - $ref: "#/definitions/EventFilter"
-    event_format:
-      description: |-
-        The format to use for events. "client" will return the events in a
-        format suitable for clients. "federation" will return the raw event
-        as receieved over federation. The default is "client".
-      type: string
-    event_fields:
-      type: array
-      description: |-
-        List of event fields to include. If this list is absent then all fields
-        are included. The entries may include "." charaters to indicate
-        sub-fields. So ["content.body"] will include the "body" field of the
-        "content" object. A server may include more fields than were requested.
-      items:
-        string
 paths:
-    "/user/{userId}/filter":
-      post:
-        summary: Upload a new filter.
+  "/user/{userId}/filter":
+    post:
+      summary: Upload a new filter.
       description: |-
         Uploads a new filter definition to the homeserver.
         Returns a filter ID that may be used in /sync requests to
@@ -135,7 +42,7 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "#/definitions/SyncFilter"
+              - $ref: "definitions/sync_filter.json"
             example:
               type: object
               example: |-
@@ -181,8 +88,57 @@ paths:
             properties:
               filter_id:
                 type: string
-                description:
+                description: |-
                   The ID of the filter that was created.
-
-
-
+  "/user/{userId}/filter/{filterId}":
+    get:
+      summary: Download a filter
+      parameters:
+        - in: path
+          name: userId
+          type: string
+          description: |-
+            The user ID to download a filter for.
+          x-example: "@alice:example.com"
+        - in: path
+          name: filterId
+          description: |-
+            The filter ID to download.
+          x-example: "66696p746572"
+      responses:
+        200:
+          examples:
+            application/json: |-
+              {
+                "room": {
+                  "state": {
+                    "types": ["m.room.*"],
+                    "not_rooms": ["!726s6s6q:example.com"]
+                  },
+                  "events": {
+                    "types": ["m.room.message"],
+                    "not_rooms": ["!726s6s6q:example.com"],
+                    "not_senders": ["@spam:example.com"]
+                  },
+                  "emphemeral": {
+                    "types": ["m.receipt", "m.typing"],
+                    "not_rooms": ["!726s6s6q:example.com"],
+                    "not_senders": ["@spam:example.com"]
+                  }
+                },
+                "public_user_data": {
+                  "types": ["m.presence"]
+                },
+                "private_user_data": {
+                  "types": []
+                },
+                "server_data": {
+                  "types": []
+                },
+                "event_format": "client",
+                "event_fields": ["type", "content", "sender"]
+              }
+          schema:
+            type: object
+            allOf:
+              - $ref: "definitions/sync_filter.json"