Merge pull request #68 from matrix-org/markjh/v2_sync_api
Swagger documentation for the v2 sync APIpull/977/head
Mark Haines
9 years ago
commit
5a5a6565ff
@ -0,0 +1 @@
|
||||
.
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"events": {
|
||||
"type": "array",
|
||||
"description": "List of events",
|
||||
"items": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,42 @@
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"description":
|
||||
"The maximum number of events to return."
|
||||
},
|
||||
"types": {
|
||||
"type": "array",
|
||||
"description":
|
||||
"A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"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. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"senders": {
|
||||
"type": "array",
|
||||
"description":
|
||||
"A list of senders IDs to include. If this list is absent then all senders are included. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"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. A matching sender will be excluded even if it is listed in the 'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"events": {
|
||||
"type": "array",
|
||||
"description": "List of event ids",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,22 @@
|
||||
{
|
||||
"type": "object",
|
||||
"allOf": [{"$ref": "definitions/event_filter.json"}],
|
||||
"properties": {
|
||||
"rooms": {
|
||||
"type": "array",
|
||||
"description":
|
||||
"A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"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. A matching room will be excluded even if it is listed in the 'rooms' filter. A '*' can be used as a wildcard to match any sequence of characters.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,44 @@
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"room": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"state": {
|
||||
"description":
|
||||
"The state events to include for rooms.",
|
||||
"allOf": [{"$ref": "definitions/room_event_filter.json"}]
|
||||
},
|
||||
"timeline": {
|
||||
"description":
|
||||
"The message and state update events to include for rooms.",
|
||||
"allOf": [{"$ref": "definitions/room_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/room_event_filter.json"}]
|
||||
}
|
||||
}
|
||||
},
|
||||
"presence": {
|
||||
"description":
|
||||
"The presence updates 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",
|
||||
"enum": ["client", "federation"]
|
||||
},
|
||||
"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 literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,14 @@
|
||||
{
|
||||
"type": "object",
|
||||
"allOf": [{"$ref":"definitions/room_event_batch.json"}],
|
||||
"properties": {
|
||||
"limited": {
|
||||
"type": "boolean",
|
||||
"description": "Whether there are more events on the server"
|
||||
},
|
||||
"prev_batch": {
|
||||
"type": "string",
|
||||
"description": "If the batch was limited then this is a token that can be supplied to the server to retrieve more events"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,139 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server v2 filter API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
basePath: /_matrix/client/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
|
||||
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/sync_filter.json"
|
||||
example: |-
|
||||
{
|
||||
"room": {
|
||||
"state": {
|
||||
"types": ["m.room.*"],
|
||||
"not_rooms": ["!726s6s6q:example.com"]
|
||||
},
|
||||
"timeline": {
|
||||
"limit": 10,
|
||||
"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"]
|
||||
}
|
||||
},
|
||||
"presence": {
|
||||
"types": ["m.presence"],
|
||||
"not_senders": ["@alice:example.com"]
|
||||
},
|
||||
"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.
|
||||
"/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"
|
||||
required: true
|
||||
- in: path
|
||||
name: filterId
|
||||
type: string
|
||||
description: |-
|
||||
The filter ID to download.
|
||||
x-example: "66696p746572"
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
"The filter defintion"
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"room": {
|
||||
"state": {
|
||||
"types": ["m.room.*"],
|
||||
"not_rooms": ["!726s6s6q:example.com"]
|
||||
},
|
||||
"timeline": {
|
||||
"limit": 10,
|
||||
"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"]
|
||||
}
|
||||
},
|
||||
"presence": {
|
||||
"types": ["m.presence"],
|
||||
"not_senders": ["@alice:example.com"]
|
||||
},
|
||||
"event_format": "client",
|
||||
"event_fields": ["type", "content", "sender"]
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "definitions/sync_filter.json"
|
||||
@ -0,0 +1,257 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server v2 sync API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
basePath: /_matrix/client/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
|
||||
paths:
|
||||
"/sync":
|
||||
get:
|
||||
summary: Synchronise the client's state and receive new messages.
|
||||
description: |-
|
||||
Synchronise the client's state with the latest state on the server.
|
||||
Client's use this API when they first log in to get an initial snapshot
|
||||
of the state on the server, and then continue to call this API to get
|
||||
incremental deltas to the state, and to receive new messages.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: filter
|
||||
type: string
|
||||
description: |-
|
||||
The ID of a filter created using the filter API.
|
||||
x-example: "66696p746572"
|
||||
- in: query
|
||||
name: since
|
||||
type: string
|
||||
description: |-
|
||||
A point in time to continue a sync from.
|
||||
x-example: "s72594_4483_1934"
|
||||
- in: query
|
||||
name: set_presence
|
||||
type: string
|
||||
enum: ["offline"]
|
||||
description: |-
|
||||
Controls whether the client is automatically marked as online by
|
||||
polling this API. If this parameter is omitted then the client is
|
||||
automatically marked as online when it uses this API. Otherwise if
|
||||
the parameter is set to "offline" then the client is not marked as
|
||||
being online when it uses this API.
|
||||
x-example: "offline"
|
||||
- in: query
|
||||
name: timeout
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum time to poll in milliseconds before returning this
|
||||
request.
|
||||
x-example: 30000
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The initial snapshot or delta for the client to use to update their
|
||||
state.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
The batch token to supply in the ``since`` param of the next
|
||||
``/sync`` request.
|
||||
rooms:
|
||||
type: object
|
||||
description: |-
|
||||
Updates to rooms.
|
||||
properties:
|
||||
joined:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
properties:
|
||||
event_map:
|
||||
type: object
|
||||
description: |-
|
||||
A map from event ID to events for this room. The
|
||||
events are referenced from the ``timeline`` and
|
||||
``state`` keys for this room.
|
||||
additionalProperties:
|
||||
description: An event object.
|
||||
type: object
|
||||
state:
|
||||
description: |-
|
||||
The state updates for the room.
|
||||
allOf:
|
||||
- $ref: "definitions/room_event_batch.json"
|
||||
timeline:
|
||||
description: |-
|
||||
The timeline of messages and state changes in the
|
||||
room.
|
||||
allOf:
|
||||
- $ref: "definitions/timeline_batch.json"
|
||||
ephemeral:
|
||||
description: |-
|
||||
The ephemeral events in the room that aren't
|
||||
recorded in the timeline or state of the room.
|
||||
e.g. typing.
|
||||
allOf:
|
||||
- $ref: "definitions/event_batch.json"
|
||||
invited:
|
||||
type: object
|
||||
description: |-
|
||||
The rooms that the user has been invited to.
|
||||
additionalProperties:
|
||||
type: object
|
||||
properties:
|
||||
invite_state:
|
||||
description: |-
|
||||
The state of a room that the user has been invited
|
||||
to. These state events may only have the `sender``,
|
||||
``type``, ``state_key`` and ``content`` keys
|
||||
present. These events do not replace any state that
|
||||
the client already has for the room, for example if
|
||||
the client has archived the room. Instead the
|
||||
client should keep two separate copies of the
|
||||
state: the one from the ``invite_state`` and one
|
||||
from the archived ``state``. If the client joins
|
||||
the room then the current state will be given as a
|
||||
delta against the archived ``state`` not the
|
||||
``invite_state``.
|
||||
allOf:
|
||||
- $ref: "definitions/event_batch.json"
|
||||
archived:
|
||||
type: object
|
||||
description: |-
|
||||
The rooms that the user has left or been banned from. The
|
||||
entries in the room_map will lack an ``ephemeral`` key.
|
||||
additionalProperties:
|
||||
type: object
|
||||
properties:
|
||||
event_map:
|
||||
type: object
|
||||
description: |-
|
||||
A map from event ID to events for this room. The
|
||||
events are referenced from the ``timeline`` and
|
||||
``state`` keys for this room.
|
||||
additionalProperties:
|
||||
description: An event object.
|
||||
type: object
|
||||
state:
|
||||
description: |-
|
||||
The state updates for the room up to the point when
|
||||
the user left.
|
||||
allOf:
|
||||
- $ref: "definitions/room_event_batch.json"
|
||||
timeline:
|
||||
description: |-
|
||||
The timeline of messages and state changes in the
|
||||
room up to the point when the user left.
|
||||
allOf:
|
||||
- $ref: "definitions/timeline_batch.json"
|
||||
presence:
|
||||
description: |-
|
||||
The updates to the presence status of other users.
|
||||
allOf:
|
||||
- $ref: "definitions/event_batch.json"
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"next_batch": "s72595_4483_1934",
|
||||
"presence": {
|
||||
"events": [
|
||||
{
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.presence",
|
||||
"content": {"presence": "online"}
|
||||
}
|
||||
]
|
||||
},
|
||||
"rooms": {
|
||||
"joined": {
|
||||
"!726s6s6q:example.com": {
|
||||
"event_map": {
|
||||
"$66697273743031:example.com": {
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@alice:example.com",
|
||||
"content": {"membership": "join"},
|
||||
"origin_server_ts": 1417731086795
|
||||
},
|
||||
"$7365636s6r6432:example.com": {
|
||||
"sender": "@bob:example.com",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@bob:example.com",
|
||||
"content": {"membership": "join"},
|
||||
"origin_server_ts": 1417731086795
|
||||
},
|
||||
"$74686972643033:example.com": {
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {"age": "124524", "txn_id": "1234"},
|
||||
"content": {
|
||||
"body": "I am a fish",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"origin_server_ts": 1417731086797
|
||||
}
|
||||
},
|
||||
"state": {
|
||||
"events": [
|
||||
"$66697273743031:example.com",
|
||||
"$7365636s6r6432:example.com"
|
||||
]
|
||||
},
|
||||
"timeline": {
|
||||
"events": [
|
||||
"$7365636s6r6432:example.com",
|
||||
"$74686972643033:example.com"
|
||||
],
|
||||
"limited": true,
|
||||
"prev_batch": "t34-23535_0_0"
|
||||
},
|
||||
"ephemeral": {
|
||||
"events": [
|
||||
{
|
||||
"room_id": "!726s6s6q:example.com",
|
||||
"type": "m.typing",
|
||||
"content": {"user_ids": ["@alice:example.com"]}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"invited": {
|
||||
"!696r7674:example.com": {
|
||||
"invite_state": {
|
||||
"events": [
|
||||
{
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.room.name",
|
||||
"state_key": "",
|
||||
"content": {"name": "My Room Name"}
|
||||
},
|
||||
{
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@bob:example.com",
|
||||
"content": {"membership": "invite"}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"archived": {}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue