Document the v2 filter GET API
This commit is contained in:
Mark Haines
parent
2f039a1142
commit
883105eae6
4 changed files with 159 additions and 101 deletions
1
api/client-server/v2_alpha/definitions/definitions
Symbolic link
1
api/client-server/v2_alpha/definitions/definitions
Symbolic link
|
|
@ -0,0 +1 @@
|
||||||
|
.
|
||||||
53
api/client-server/v2_alpha/definitions/event_filter.json
Normal file
53
api/client-server/v2_alpha/definitions/event_filter.json
Normal file
|
|
@ -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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
48
api/client-server/v2_alpha/definitions/sync_filter.json
Normal file
48
api/client-server/v2_alpha/definitions/sync_filter.json
Normal file
|
|
@ -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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -16,99 +16,6 @@ securityDefinitions:
|
||||||
description: The user_id or application service access_token
|
description: The user_id or application service access_token
|
||||||
name: access_token
|
name: access_token
|
||||||
in: query
|
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:
|
paths:
|
||||||
"/user/{userId}/filter":
|
"/user/{userId}/filter":
|
||||||
post:
|
post:
|
||||||
|
|
@ -135,7 +42,7 @@ paths:
|
||||||
schema:
|
schema:
|
||||||
type: object
|
type: object
|
||||||
allOf:
|
allOf:
|
||||||
- $ref: "#/definitions/SyncFilter"
|
- $ref: "definitions/sync_filter.json"
|
||||||
example:
|
example:
|
||||||
type: object
|
type: object
|
||||||
example: |-
|
example: |-
|
||||||
|
|
@ -181,8 +88,57 @@ paths:
|
||||||
properties:
|
properties:
|
||||||
filter_id:
|
filter_id:
|
||||||
type: string
|
type: string
|
||||||
description:
|
description: |-
|
||||||
The ID of the filter that was created.
|
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"
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue