Add swagger docs for the v2 filter POST API
Mark Haines
9 years ago
parent
ca9f30a7fd
commit
2f039a1142
@ -0,0 +1,188 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server v2 filter API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
basePath: /_matrix/client/api/v2_alpha
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
accessToken:
|
||||
type: apiKey
|
||||
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.
|
||||
description: |-
|
||||
Uploads a new filter definition to the homeserver.
|
||||
Returns a filter ID that may be used in /sync requests to
|
||||
retrict which events are returned to the client.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description:
|
||||
The id of the user uploading the filter. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
x-example: "@alice:example.com"
|
||||
- in: body
|
||||
name: filter
|
||||
required: true
|
||||
description: The filter to upload.
|
||||
schema:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "#/definitions/SyncFilter"
|
||||
example:
|
||||
type: object
|
||||
example: |-
|
||||
{
|
||||
"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"]
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The filter was created.
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"filter_id": "66696p746572"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
filter_id:
|
||||
type: string
|
||||
description:
|
||||
The ID of the filter that was created.
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue