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,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"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue