wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' of github.com:matrix-org/matrix-doc into erikj/public_rooms

Browse source
This commit is contained in:
Erik Johnston 2016-10-11 14:31:47 +01:00
commit a69d6c63c6
34 changed files with 857 additions and 186 deletions
Download patch file Download diff file Expand all files Collapse all files

7
api/client-server/create_room.yaml
View file

@ -170,7 +170,12 @@ paths:
``public_chat``: =>
``join_rules`` is set to ``public``.
``history_visibility`` is set to ``shared``.
is_direct:
type: boolean
description: |-
This flag makes the server set the ``is_direct`` flag on the
``m.room.member`` events sent to the users in ``invite`` and
``invite_3pid``. See `Direct Messaging`_ for more information.
responses:
200:
description: Information about the newly created room.

4
api/client-server/definitions/room_event_filter.yaml
View file

@ -28,4 +28,8 @@ properties:
items:
type: string
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a url key in their content. If
``false``, excludes those events.
type: object

2
api/client-server/definitions/security.yaml
View file

@ -13,6 +13,6 @@
# limitations under the License.
accessToken:
type: apiKey
description: The access_token returned by a call to ``/login`` or ``/tokenrefresh``
description: The access_token returned by a call to ``/login`` or ``/register``
name: access_token
in: query

73
api/client-server/login.yaml
View file

@ -90,15 +90,6 @@ paths:
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
There is no specific error message to indicate that a request has failed because
an access token has expired; instead, if a client has reason to believe its
access token is valid, and it receives an auth error, they should attempt to
refresh for a new token on failure, and retry the request with the new token.
refresh_token:
type: string
description: |-
Optional. A ``refresh_token`` may be exchanged for a new ``access_token`` using the |/tokenrefresh|_ API endpoint.
home_server:
type: string
description: The hostname of the homeserver on which the account has been registered.
@ -123,67 +114,3 @@ paths:
"$ref": "definitions/error.yaml"
tags:
- Session management
"/tokenrefresh":
post:
summary: Exchanges a refresh token for an access token.
description: |-
Exchanges a refresh token for a new access token.
This is intended to be used if the access token has expired.
The server MUST invalidate the supplied ``refresh_token`` if the
request is successful. It MUST also invalidate the ``access_token``
which was issued at the same time as the ``refresh_token``, if it
has not already expired.
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: |-
{
"refresh_token": "a1b2c3"
}
properties:
refresh_token:
type: string
description: The refresh token which was issued by the server.
required: ["refresh_token"]
responses:
200:
description: |-
The refresh token was accepted, and a new access token has been issued.
The passed refresh token is no longer valid and cannot be used.
A new refresh token will have been returned unless some policy does
not allow the user to continue to renew their session.
examples:
application/json: |-
{
"access_token": "bearwithme123",
"refresh_token": "exchangewithme987"
}
schema:
type: object
properties:
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
refresh_token:
type: string
description: Optional. A new ``refresh_token`` which may be exchanged for another new ``access_token``.
403:
description: |-
The exchange attempt failed. For example, the refresh token may have already been used.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN"}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management

7
api/client-server/message_pagination.yaml
View file

@ -75,6 +75,13 @@ paths:
description: |-
The maximum number of events to return. Default: 10.
x-example: "3"
- in: query
type: string
name: filter
description: |-
A JSON RoomEventFilter to filter returned events with.
x-example: |-
{"contains_url":true}
responses:
200:
description: A list of messages with a new token to request more.

142
api/client-server/notifications.yaml Normal file
View file

@ -0,0 +1,142 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Notifications API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/notifications":
get:
summary: Gets a list of events that the user has been notified about
description: |-
This API is used to paginate through the list of events that the
user has been, or would have been notified about.
security:
- accessToken: []
parameters:
- in: query
type: string
name: from
description: Pagination token given to retrieve the next set of events.
required: false
x-example: "xxxxx"
- in: query
type: number
name: limit
description: Limit on the number of events to return in this request.
required: false
x-example: "20"
- in: query
name: only
type: string
description: |-
Allows basic filtering of events returned. Supply ``highlight``
to return only events where the notification had the highlight
tweak set.
required: false
x-example: "highlight"
responses:
200:
description: A batch of events is being returned
examples:
application/json: |-
{
"next_token": "abcdef",
"notifications": [
{
"actions": [
"notify"
],
"profile_tag": "hcbvkzxhcvb",
"read": true,
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"sender": "@alice:example.com",
"type": "m.room.message",
"age": 124524,
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
}
}
]
}
schema:
type: object
required: ["notifications"]
properties:
next_token:
type: string
description: |-
The token to supply in the ``from`` param of the next
``/notifications`` request in order to request more
events. If this is absent, there are no more results.
notifications:
type: array
items:
type: object
required: ["actions", "event", "read", "room_id", "ts"]
title: Notification
properties:
actions:
type: array
description: |-
The action(s) to perform when the conditions for this rule are met.
See `Push Rules: API`_.
items:
type:
- object
- string
event:
type: object
title: Event
description: The Event object for the event that triggered the notification.
allOf:
- "$ref": "definitions/event.yaml"
profile_tag:
type: string
description: The profile tag of the rule that matched this event.
read:
type: boolean
description: |-
Indicates whether the user has sent a read receipt indicating
that they have read this message.
room_id:
type: string
description: The ID of the room in which the event was posted.
ts:
type: integer
description: |-
The unix timestamp at which the event notification was sent,
in milliseconds.
description: The list of events that triggered notifications.
tags:
- Push notifications

16
api/client-server/registration.yaml
View file

@ -39,6 +39,9 @@ paths:
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
If registration is successful, this endpoint will issue an access token
the client can use to authorize itself in subsequent requests.
parameters:
- in: query
name: kind
@ -90,8 +93,7 @@ paths:
{
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"home_server": "matrix.org",
"refresh_token": "def456"
"home_server": "matrix.org"
}
schema:
type: object
@ -104,16 +106,6 @@ paths:
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
There is no specific error message to indicate that a request has failed because
an access token has expired; instead, if a client has reason to believe its
access token is valid, and it receives an auth error, they should attempt to
refresh for a new token on failure, and retry the request with the new token.
refresh_token:
type: string
# TODO: Work out how to linkify /tokenrefresh
description: |-
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server:
type: string
description: The hostname of the homeserver on which the account has been registered.

2
api/client-server/rooms.yaml
View file

@ -246,7 +246,7 @@ paths:
200:
description: |-
A list of members of the room. If you are joined to the room then
this will be the current members of the room. If you have left te
this will be the current members of the room. If you have left the
room then this will be the members of the room when you left.
examples:
application/json: |-

6
api/client-server/sync.yaml
View file

@ -236,6 +236,12 @@ paths:
The global private data created by this user.
allOf:
- $ref: "definitions/event_batch.yaml"
to_device:
title: ToDevice
type: object
description: |-
Information on the send-to-device messages for the client
device, as defined in |send_to_device_sync|_.
examples:
application/json: |-
{

89
api/client-server/to_device.yaml Normal file
View file

@ -0,0 +1,89 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Send-to-device API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/sendToDevice/{eventType}/{txnId}":
put:
summary: Send an event to a given set of devices.
description: |-
This endpoint is used to send send-to-device events to a set of
client devices.
security:
- accessToken: []
parameters:
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.new_device"
- in: path
name: txnId
type: string
description: |-
The transaction ID for this event. Clients should generate an
ID unique across requests with the same access token; it will be
used by the server to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
required: true
schema:
type: object
title: body
properties:
messages:
type: object
description: |-
The messages to send. A map from user ID, to a map from
device ID to message body. The device ID may also be `*`,
meaning all known devices for the user.
additionalProperties:
type: object
additionalProperties:
type: object
title: EventContent
description: Message content
example: {
"@alice:example.com": {
"TLLBEANAAG": {
"example_content_key": "value"
}
}
}
responses:
200:
description:
The message was successfully sent.
examples:
application/json: |-
{}
tags:
- Send-to-Device messaging