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

Merge remote-tracking branch 'matrix-org/master' into travis/s2s/backfill

Browse source
This commit is contained in:
Travis Ralston 2018-08-07 08:54:25 -06:00
commit 521dcdd5d5
15 changed files with 554 additions and 245 deletions
Download patch file Download diff file Expand all files Collapse all files

69
api/server-server/directory.yaml
View file

@ -1,69 +0,0 @@
# Copyright 2017 Kamax.io
# Copyright 2018 New Vector 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 Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/query/directory":
get:
summary: Retrieve the room ID and list of resident homeservers for a room
alias.
description: Retrieve the room ID and list of resident homeservers for a room
alias.
parameters:
- in: query
name: room_alias
type: string
description: Room alias.
required: true
x-example: "#room_alias:example.org"
responses:
200:
description: The corresponding room ID and list of known resident
homeservers for the room.
schema:
type: object
properties:
room_id:
type: string
description: The room ID mapped to the queried room alias.
x-example: "!roomid1234:example.org"
servers:
type: array
description: An array of server names that are likely to hold
then given room. This list may or may not include the server
answering the query.
items:
type: string
required:
- "room_id"
- "servers"
examples:
application/json: {
"room_id": "!roomid1234:example.org",
"servers": [
"example.org",
"example.com",
"another.example.com:8449",
]
}

174
api/server-server/event_auth.yaml Normal file
View file

@ -0,0 +1,174 @@
# Copyright 2018 New Vector 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 Federation Event Authorization API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths:
"/event_auth/{roomId}/{eventId}":
get:
summary: Get the auth chain for a given event
description: |-
Retrieves the complete auth chain for a given event.
operationId: getEventAuth
parameters:
- in: path
name: roomId
type: string
description: The room ID to get the auth chain for.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID to get the auth chain of.
required: true
x-example: "$helloworld:domain.com"
responses:
200:
description: The auth chain for the event.
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The full set of authorization events that make up the state of
the room, and their authorization events, recursively.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
required: ['auth_chain']
"/query_auth/{roomId}/{eventId}":
post:
summary: Compare auth chains with the receiving server
description: |-
Compares the auth chain provided with what the receiving server has for the
room ID and event ID combination.
The auth difference can be calculated in two parts, where the "remote auth"
is the auth chain provided by the sending server and the "local auth" is the
auth chain the receiving server has. With those lists, the algorithm works
bottom-up after sorting each chain by depth then by event ID. The differences
are then discovered and returned as the response to this API call.
operationId: compareEventAuth
parameters:
- in: path
name: roomId
type: string
description: The room ID to compare the auth chain in.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID to compare the auth chain of.
required: true
x-example: "$helloworld:domain.com"
- in: body
name: body
schema:
type: object
properties:
auth_chain:
type: array
description: The auth chain (the "remote auth").
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
missing:
type: array
description: |-
A list of event IDs that the sender thinks the receiver is missing.
items:
type: string
example: []
rejects:
type: object
description: |-
The set of events that the sending server has rejected from the provided
auth chain.
The ``string`` key is the event ID that was rejected.
additionalProperties:
type: object
title: Rejection Reason
properties:
reason:
type: enum
enum: ['auth_error', 'replaced', 'not_ancestor']
description: |-
The reason for the event being rejected.
required: ['reason']
example: {
"$some_event:domain.com": {
"reason": "auth_error"
}
}
required: ['auth_chain']
responses:
200:
description: The auth chain differences, as determined by the receiver.
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The auth chain the receiver has, and used to determine the auth
chain differences (the "local auth").
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
missing:
type: array
description: |-
The list of event IDs that the receiver believes it is missing,
after comparing the "remote auth" and "local auth" chains.
items:
type: string
example: ["$a_missing_event:domain.com"]
rejects:
type: object
description: |-
The set of events that the receiving server has rejected from the
auth chain, not including events that the sending server is missing
as determined from the difference algorithm.
The ``string`` key is the event ID that was rejected.
additionalProperties:
type: object
title: Rejection Reason
properties:
reason:
type: enum
enum: ['auth_error', 'replaced', 'not_ancestor']
description: |-
The reason for the event being rejected.
required: ['reason']
example: {
"$some_event:domain.com": {
"reason": "auth_error"
}
}
required: ['auth_chain', 'missing', 'rejects']

2
api/server-server/joins.yaml
View file

@ -20,6 +20,8 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths:

2
api/server-server/keys_query.yaml
View file

@ -20,6 +20,8 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
consumes:
- application/json
produces:
- application/json
paths:

2
api/server-server/leaving.yaml
View file

@ -20,6 +20,8 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths:

52
api/server-server/public_rooms.yaml Normal file
View file

@ -0,0 +1,52 @@
# Copyright 2018 New Vector 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 Federation Public Rooms API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/publicRooms":
get:
summary: Get all the public rooms for a homeserver
description: |-
Gets all the public rooms for the homeserver. This should not return
rooms that are listed on another homeserver's directory, just those
listed on the receiving homeserver's directory.
operationId: getPublicRooms
parameters:
- in: query
name: limit
type: integer
description: |-
The maximum number of rooms to return. Defaults to 0 (no limit).
x-example: 10
- in: query
name: since
type: string
description: |-
A pagination token from a previous call to this endpoint to fetch more
rooms.
x-example: "GetMoreRoomsTokenHere"
responses:
200:
description: The public room list for the homeserver.
schema:
$ref: "../client-server/definitions/public_rooms_response.yaml"

166
api/server-server/query.yaml Normal file
View file

@ -0,0 +1,166 @@
# Copyright 2017 Kamax.io
# Copyright 2018 New Vector 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 Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/query/{queryType}":
get:
summary: Query for information
description: |-
Performs a single query request on the receiving homeserver. The query string
arguments are dependent on which type of query is being made. Known query types
are specified as their own endpoints as an extension to this definition.
operationId: queryInfo
parameters:
- in: path
name: queryType
type: string
description: The type of query to make
required: true
x-example: profile
responses:
200:
description: |-
The query response. The schema varies depending on the query being made.
"/query/directory":
get:
summary: Query for the room ID and resident homeservers for a room alias
description: |-
Performs a query to get the mapped room ID and list of resident homeservers in
the room for a given room alias. Homeservers should only query room aliases
that belong to the target server (identified by the DNS Name in the alias).
Servers may wish to cache the response to this query to avoid requesting the
information too often.
operationId: queryRoomDirectory
parameters:
- in: query
name: room_alias
type: string
description: The room alias to query.
required: true
x-example: "#room_alias:example.org"
responses:
200:
description: |-
The corresponding room ID and list of known resident homeservers for the room.
schema:
type: object
properties:
room_id:
type: string
description: The room ID mapped to the queried room alias.
x-example: "!roomid1234:example.org"
servers:
type: array
description: |-
An array of server names that are likely to hold the given room. This
list may or may not include the server answering the query.
items:
type: string
required:
- "room_id"
- "servers"
examples:
application/json: {
"room_id": "!roomid1234:example.org",
"servers": [
"example.org",
"example.com",
"another.example.com:8449",
]
}
404:
description: The room alias was not found.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias not found."
}
"/query/profile":
get:
summary: Query for profile information about a given user
description: |-
Performs a query to get profile information, such as a display name or avatar,
for a given user. Homeservers should only query profiles for users that belong
to the target server (identified by the DNS Name in the user ID).
Servers may wish to cache the response to this query to avoid requesting the
information too often.
parameters:
- in: query
name: user_id
type: string
description: The user ID to query.
required: true
x-example: "@someone:example.org"
- in: query
name: field
type: enum
enum: ['displayname', 'avatar_url']
description: |-
The field to query. If specified, the server will only return the given field
in the response. If not specified, the server will return the full profile for
the user.
responses:
200:
description: |-
The profile for the user. If a ``field`` is specified in the request, only the
matching field should be included in the response. If no ``field`` was specified,
the response should include the fields of the user's profile that can be made
public, such as the display name and avatar.
If the user does not have a particular field set on their profile, the server
should exclude it from the response body or give it the value ``null``.
schema:
type: object
properties:
displayname:
type: string
description: |-
The display name of the user. May be omitted if the user does not have a
display name set.
x-example: "John Doe"
avatar_url:
type: string
description: |-
The avatar URL for the user's avatar. May be omitted if the user does not
have an avatar set.
x-example: "mxc://matrix.org/MyC00lAvatar"
examples:
application/json: {
"displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
}
404:
description: The user does not exist or does not have a profile.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "User does not exist."
}

44
api/server-server/query_general.yaml
View file

@ -1,44 +0,0 @@
# Copyright 2018 New Vector 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 Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/query/{queryType}":
get:
summary: Query for information
description: |-
Performs a single query request on the receiving homeserver. The query string
arguments are dependent on which type of query is being made. Known query types
are specified as their own endpoints as an extension to this definition.
operationId: queryInfo
parameters:
- in: path
name: queryType
type: string
description: The type of query to make
required: true
x-example: profile
responses:
200:
description: |-
The query response. The schema varies depending on the query being made.

2
api/server-server/third_party_invite.yaml
View file

@ -20,6 +20,8 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths:

2
api/server-server/transactions.yaml
View file

@ -20,6 +20,8 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths: