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

Merge remote-tracking branch 'origin/master' into erikj/search_actual

Browse source
This commit is contained in:
Erik Johnston 2015-10-19 13:46:58 +01:00
commit 1d01f69c3c
30 changed files with 1020 additions and 403 deletions
Download patch file Download diff file Expand all files Collapse all files

148
api/client-server/v1/create_room.yaml Normal file
View file

@ -0,0 +1,148 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
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:
"/createRoom":
post:
summary: Create a new room
description: |-
Create a new room with various configuration options.
security:
- accessToken: []
parameters:
- in: body
name: body
description: The desired room configuration.
schema:
type: object
example: |-
{
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
}
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
A ``public`` visibility indicates that the room will be shown
in the published room list. A ``private`` visibility will hide
the room from the published room list. Rooms default to
``private`` visibility if this key is not included. NB: This
should not be confused with ``join_rules`` which also uses the
word ``public``.
room_alias_name:
type: string
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* home server which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
name:
type: string
description: |-
If this is included, an ``m.room.name`` event will be sent
into the room to indicate the name of the room. See Room
Events for more information on ``m.room.name``.
topic:
type: string
description: |-
If this is included, an ``m.room.topic`` event will be sent
into the room to indicate the topic for the room. See Room
Events for more information on ``m.room.topic``.
invite:
type: array
description: |-
A list of user IDs to invite to the room. This will tell the
server to invite everyone in the list to the newly created room.
items:
type: string
creation_content:
title: CreationContent
type: object
description: |-
Extra keys to be added to the content of the ``m.room.create``.
The server will clober the following keys: ``creator``. Future
versions of the specification may allow the server to clobber
other keys.
initial_state:
type: array
description: |-
A list of state events to set in the new room. This allows
the user to override the default state events set in the new
room. The expected format of the state events are an object
with type, state_key and content keys set.
Takes precedence over events set by ``presets``, but gets
overriden by ``name`` and ``topic`` keys.
items:
type: object
title: StateEvent
properties:
type:
type: string
state_key:
type: string
content:
type: string
preset:
type: string
enum: ["private_chat", "public_chat", "trusted_private_chat"]
description: |-
Convenience parameter for setting various default state events
based on a preset. Must be either:
``private_chat`` =>
``join_rules`` is set to ``invite``.
``history_visibility`` is set to ``shared``.
``trusted_private_chat`` =>
``join_rules`` is set to ``invite``.
``history_visibility`` is set to ``shared``.
All invitees are given the same power level as the room creator.
``public_chat``: =>
``join_rules`` is set to ``public``.
``history_visibility`` is set to ``shared``.
responses:
200:
description: Information about the newly created room.
schema:
type: object
description: Information about the newly created room.
properties:
room_id:
type: string
description: |-
The created room's ID.
examples:
application/json: |-
{
"room_id": "!sefiuhWgwghwWgh:example.com"
}
400:
description: >
The request body is malformed or the room alias specified is already taken.

19
api/client-server/v1/login.yaml
View file

@ -33,17 +33,21 @@ paths:
type: object
example: |-
{
"username": "cheeky_monkey",
"type": "m.login.pasword",
"user": "cheeky_monkey",
"password": "ilovebananas"
}
properties:
username:
type:
type: string
description: The login type being used. Currently only "m.login.password" is supported.
user:
type: string
description: The fully qualified user ID or just local part of the user ID, to log in.
password:
type: string
description: The user's password.
required: ["username", "password"]
required: ["type", "user", "password"]
responses:
200:
description: The user has been authenticated.
@ -78,6 +82,15 @@ paths:
home_server:
type: string
description: The hostname of the Home Server on which the account has been registered.
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
examples:
application/json: |-
{
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
403:
description: |-
The login attempt failed. For example, the password may have been incorrect.

131
api/client-server/v1/message_pagination.yaml Normal file
View file

@ -0,0 +1,131 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
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:
"/rooms/{roomId}/messages":
get:
summary: Get a list of events for this room
description: |-
This API returns a list of message and state events for a room. It uses
pagination query parameters to paginate history in the room.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get events from.
required: true
x-example: "!636q39766251:example.com"
- in: query
type: string
name: from
description: |-
The token to start returning events from. This token can be obtained
from the initial sync API.
required: true
x-example: "s345_678_333"
- in: query
type: string
enum: ["b", "f"]
name: dir
description: |-
The direction to return events from.
required: true
x-example: "b"
- in: query
type: integer
name: limit
description: |-
The maximum number of events to return. Default: 10.
x-example: "3"
responses:
200:
description: A list of messages with a new token to request more.
schema:
type: object
description: A list of messages with a new token to request more.
properties:
start:
type: string
description: |-
The token to start paginating from. If ``dir=b`` this will be
the token supplied in ``from``.
end:
type: string
description: |-
The token the pagination ends at. If ``dir=b`` this token should
be used again to request even earlier events.
chunk:
type: array
description: |-
A list of room events.
items:
type: object
title: RoomEvent
examples:
application/json: |-
{
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"origin_server_ts": 1444812213737,
"user_id": "@alice:example.com",
"event_id": "$1444812213350496Caaaa:example.com",
"content": {
"body": "hello world",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 1042
},
{
"origin_server_ts": 1444812194656 ,
"user_id": "@bob:example.com",
"event_id": "$1444812213350496Cbbbb:example.com",
"content": {
"body": "the world is big",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 20123
},
{
"origin_server_ts": 1444812163990,
"user_id": "@bob:example.com",
"event_id": "$1444812213350496Ccccc:example.com",
"content": {
"name": "New room name"
},
"prev_content": {
"name": "Old room name"
},
"state_key": "",
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.name",
"age": 50789
}
]
}
403:
description: >
You aren't a member of the room.

34
api/client-server/v1/sync.yaml
View file

@ -30,7 +30,9 @@ paths:
- in: query
type: string
name: from
description: The token to stream from.
description: |-
The token to stream from. This token is either from a previous
request to this API or from the initial sync API.
required: false
x-example: "s3456_9_0"
- in: query
@ -39,16 +41,6 @@ paths:
description: The maximum time in milliseconds to wait for an event.
required: false
x-example: "35000"
- in: query
type: string
name: archived
description: |-
Whether to include rooms that the user has left. If absent then
only rooms that the user has been invited to or has joined are
included. If set to "true" then rooms that the user has left are
included as well.
required: false
x-example: "true"
responses:
200:
description: "The events received, which may be none."
@ -78,19 +70,19 @@ paths:
start:
type: string
description: |-
A token which correlates to the first value in ``chunk``. Used
for pagination.
A token which correlates to the first value in ``chunk``. This
is usually the same token supplied to ``from=``.
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``. Used
for pagination.
A token which correlates to the last value in ``chunk``. This
token should be used in the next request to ``/events``.
chunk:
type: array
description: "An array of events."
items:
type: object
title: RoomEvent
title: Event
allOf:
- "$ref": "core-event-schema/room_event.json"
400:
@ -110,6 +102,16 @@ paths:
description: The maximum number of messages to return for each room.
required: false
x-example: "2"
- in: query
type: boolean
name: archived
description: |-
Whether to include rooms that the user has left. If ``false`` then
only rooms that the user has been invited to or has joined are
included. If set to ``true`` then rooms that the user has left are
included as well. By default this is ``false``.
required: false
x-example: "true"
responses:
200:
description: The user's current state.

101
api/client-server/v2_alpha/registration.yaml Normal file
View file

@ -0,0 +1,101 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 Registration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v2_alpha
consumes:
- application/json
produces:
- application/json
paths:
"/register":
post:
summary: Register for an account on this homeserver.
description: |-
Register for an account on this homeserver.
parameters:
- in: body
name: body
schema:
type: object
example: |-
{
"username": "cheeky_monkey",
"password": "ilovebananas",
"bind_email": false
}
properties:
bind_email:
type: boolean
description: |-
If true, the server binds the email used for authentication to
the Matrix ID with the ID Server.
username:
type: string
description: |-
The local part of the desired Matrix ID. If omitted,
the homeserver MUST generate a Matrix ID local part.
password:
type: string
description: The desired password for the account.
required: ["password"]
responses:
200:
description: The account has been registered.
examples:
application/json: |-
{
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"home_server": "matrix.org",
"refresh_token": "def456"
}
schema:
type: object
properties:
user_id:
type: string
description: The fully-qualified Matrix ID that has been registered.
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``.
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 Home Server on which the account has been registered.
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_USER_IN_USE`` : The desired user ID is already taken.
* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
claimed by an application service.
These errors may be returned at any stage of the registration process,
including after authentication if the requested user ID was registered
whilst the client was performing authentication.
examples:
application/json: |-
{
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"