Merge pull request #1554 from turt2live/travis/general/appservice-directories
Application service room directories (and other third party network things)
This commit is contained in:
commit
97508d5dc5
12 changed files with 496 additions and 276 deletions
|
@ -96,243 +96,3 @@ paths:
|
|||
}
|
||||
schema:
|
||||
type: object
|
||||
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
|
||||
get:
|
||||
summary: Retrieve metadata about a specific protocol that the application service supports.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to present clients
|
||||
with specific information about the various third party networks that
|
||||
an application service supports.
|
||||
operationId: getProtocolMetadata
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
responses:
|
||||
200:
|
||||
description: The protocol was found and metadata returned.
|
||||
schema:
|
||||
$ref: definitions/protocol_metadata.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No protocol was found with the given path.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user/{protocol}":
|
||||
get:
|
||||
summary: Retrieve the Matrix User ID of a corresponding third party user.
|
||||
description: |-
|
||||
This API is called by the homeserver in order to retrieve a Matrix
|
||||
User ID linked to a user on the third party network, given a set of
|
||||
user parameters.
|
||||
operationId: queryUserByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the user.
|
||||
responses:
|
||||
200:
|
||||
description: The Matrix User IDs found with the given parameters.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No users were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retreive Matrix-side portal rooms leading to a third party location.
|
||||
description: |-
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
|
||||
operationId: queryLocationByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the third party location.
|
||||
responses:
|
||||
200:
|
||||
description: At least one portal room was found.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location":
|
||||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retreive an array of third party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
parameters:
|
||||
- in: query
|
||||
name: alias
|
||||
type: string
|
||||
description: The Matrix room alias to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
All found third party locations.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user":
|
||||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retreive an array of third party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
parameters:
|
||||
- in: query
|
||||
name: userid
|
||||
type: string
|
||||
description: The Matrix User ID to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An array of third party users.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
|
|
|
@ -19,12 +19,14 @@ properties:
|
|||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
type: string
|
||||
example: irc
|
||||
example: "irc"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
type: object
|
||||
example:
|
||||
"network": "freenode"
|
||||
example: {
|
||||
"network": "freenode",
|
||||
"channel": "#matrix"
|
||||
}
|
||||
required: ['alias', 'protocol', 'fields']
|
||||
title: Location
|
||||
type: object
|
|
@ -11,41 +11,60 @@
|
|||
# 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.
|
||||
title: Protocol
|
||||
type: object
|
||||
properties:
|
||||
user_fields:
|
||||
description: Fields used to identify a third party user.
|
||||
description: |-
|
||||
Fields which may be used to identify a third party user. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the nickname of a user.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party user.
|
||||
example: ["network", "nickname"]
|
||||
location_fields:
|
||||
description: Fields used to identify a third party location.
|
||||
description: |-
|
||||
Fields which may be used to identify a third party location. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the name of a channel.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party location.
|
||||
example: ["network", "channel"]
|
||||
icon:
|
||||
description: An icon representing the third party protocol.
|
||||
description: A content URI representing an icon for the third party protocol.
|
||||
type: string
|
||||
example: "mxc://example.org/aBcDeFgH"
|
||||
field_types:
|
||||
title: Field Types
|
||||
description: All location or user fields should have an entry here.
|
||||
description: |-
|
||||
The type definitions for the fields defined in the ``user_fields`` and
|
||||
``location_fields``. Each entry in those arrays MUST have an entry here. The
|
||||
``string`` key for this object is field name itself.
|
||||
|
||||
May be an empty object if no fields are defined.
|
||||
type: object
|
||||
properties:
|
||||
fieldname:
|
||||
title: Field Type
|
||||
description: Definition of valid values for a field.
|
||||
type: object
|
||||
properties:
|
||||
regexp:
|
||||
description: A regular expression for validation of a field's value.
|
||||
type: string
|
||||
placeholder:
|
||||
description: An placeholder serving as a valid example of the field value.
|
||||
type: string
|
||||
additionalProperties:
|
||||
title: Field Type
|
||||
description: Definition of valid values for a field.
|
||||
type: object
|
||||
properties:
|
||||
regexp:
|
||||
description: |-
|
||||
A regular expression for validation of a field's value. This may be relatively
|
||||
coarse to verify the value as the application service providing this protocol
|
||||
may apply additional validation or filtering.
|
||||
type: string
|
||||
placeholder:
|
||||
description: An placeholder serving as a valid example of the field value.
|
||||
type: string
|
||||
required: ['regexp', 'placeholder']
|
||||
required: ['fieldname']
|
||||
example: {
|
||||
"network": {
|
||||
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
|
||||
|
@ -63,17 +82,32 @@ properties:
|
|||
instances:
|
||||
description: |-
|
||||
A list of objects representing independent instances of configuration.
|
||||
For instance multiple networks on IRC if multiple are bridged by the
|
||||
same bridge.
|
||||
For example, multiple networks on IRC if multiple are provided by the
|
||||
same application service.
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
example: {
|
||||
"desc": "Freenode",
|
||||
"icon": "mxc://example.org/JkLmNoPq",
|
||||
"fields": {
|
||||
"network": "freenode.net",
|
||||
}
|
||||
}
|
||||
title: Protocol
|
||||
type: object
|
||||
title: Protocol Instance
|
||||
properties:
|
||||
desc:
|
||||
type: string
|
||||
description: A human-readable description for the protocol, such as the name.
|
||||
example: "Freenode"
|
||||
icon:
|
||||
type: string
|
||||
description: |-
|
||||
An optional content URI representing the protocol. Overrides the one provided
|
||||
at the higher level Protocol object.
|
||||
example: "mxc://example.org/JkLmNoPq"
|
||||
fields:
|
||||
type: object
|
||||
description: Preset values for ``fields`` the client may use to search by.
|
||||
example: {
|
||||
"network": "freenode"
|
||||
}
|
||||
network_id:
|
||||
type: string
|
||||
description: A unique identifier across all instances.
|
||||
example: "freenode"
|
||||
required: ['desc', 'fields', 'network_id']
|
||||
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
|
||||
|
|
|
@ -36,6 +36,7 @@ example: {
|
|||
},
|
||||
"instances": [
|
||||
{
|
||||
"network_id": "freenode",
|
||||
"desc": "Freenode",
|
||||
"icon": "mxc://example.org/JkLmNoPq",
|
||||
"fields": {
|
||||
|
@ -59,6 +60,7 @@ example: {
|
|||
},
|
||||
"instances": [
|
||||
{
|
||||
"network_id": "gitter",
|
||||
"desc": "Gitter",
|
||||
"icon": "mxc://example.org/zXyWvUt",
|
||||
"fields": {}
|
||||
|
|
|
@ -21,11 +21,13 @@ properties:
|
|||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
type: string
|
||||
example: gitter
|
||||
example: "gitter"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
type: object
|
||||
example:
|
||||
example: {
|
||||
"user": "jim"
|
||||
}
|
||||
required: ['userid', 'protocol', 'fields']
|
||||
title: User
|
||||
type: object
|
267
api/application-service/protocols.yaml
Normal file
267
api/application-service/protocols.yaml
Normal file
|
@ -0,0 +1,267 @@
|
|||
# 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 Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: "/"
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
paths:
|
||||
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
|
||||
get:
|
||||
summary: Retrieve metadata about a specific protocol that the application service supports.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to present clients
|
||||
with specific information about the various third party networks that
|
||||
an application service supports.
|
||||
operationId: getProtocolMetadata
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
responses:
|
||||
200:
|
||||
description: The protocol was found and metadata returned.
|
||||
schema:
|
||||
$ref: definitions/protocol_metadata.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No protocol was found with the given path.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user/{protocol}":
|
||||
get:
|
||||
summary: Retrieve the Matrix User ID of a corresponding third party user.
|
||||
description: |-
|
||||
This API is called by the homeserver in order to retrieve a Matrix
|
||||
User ID linked to a user on the third party network, given a set of
|
||||
user parameters.
|
||||
operationId: queryUserByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the user.
|
||||
responses:
|
||||
200:
|
||||
description: The Matrix User IDs found with the given parameters.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No users were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retrieve Matrix-side portal rooms leading to a third party location.
|
||||
description: |-
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
|
||||
operationId: queryLocationByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the third party location.
|
||||
responses:
|
||||
200:
|
||||
description: At least one portal room was found.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location":
|
||||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retrieve an array of third party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
parameters:
|
||||
- in: query
|
||||
name: alias
|
||||
type: string
|
||||
description: The Matrix room alias to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
All found third party locations.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user":
|
||||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retrieve an array of third party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
parameters:
|
||||
- in: query
|
||||
name: userid
|
||||
type: string
|
||||
description: The Matrix User ID to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An array of third party users.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
87
api/client-server/appservice_room_directory.yaml
Normal file
87
api/client-server/appservice_room_directory.yaml
Normal file
|
@ -0,0 +1,87 @@
|
|||
# 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 Client-Server Application Service Room Directory API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
# Note: this is the same access_token definition used elsewhere in the client
|
||||
# server API, however this expects an access token for an application service.
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/directory/list/appservice/{networkId}/{roomId}":
|
||||
put:
|
||||
summary: |-
|
||||
Updates a room's visibility in the application service's room directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room on the application service's room
|
||||
directory.
|
||||
|
||||
This API is similar to the room directory visibility API used by clients
|
||||
to update the homeserver's more general room directory.
|
||||
|
||||
This API requires the use of an application service access token (``as_token``)
|
||||
instead of a typical client's access_token. This API cannot be invoked by
|
||||
users who are not identified as application services.
|
||||
operationId: updateAppserviceRoomDirectoryVsibility
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: networkId
|
||||
description: |-
|
||||
The protocol (network) ID to update the room list for. This would
|
||||
have been provided by the application service as being listed as
|
||||
a supported protocol.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room ID to add to the directory.
|
||||
required: true
|
||||
x-example: "!somewhere:domain.com"
|
||||
- in: body
|
||||
name: body
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
visibility:
|
||||
type: enum
|
||||
enum: ["public", "private"]
|
||||
description: |-
|
||||
Whether the room should be visible (public) in the directory
|
||||
or not (private).
|
||||
example: "public"
|
||||
required: ['visibility']
|
||||
security:
|
||||
# again, this is the appservice's token - not a typical client's
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The room's directory visibility has been updated.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: {}
|
||||
tags:
|
||||
- Application service room directory management
|
|
@ -194,8 +194,26 @@ paths:
|
|||
description: |-
|
||||
A string to search for in the room metadata, e.g. name,
|
||||
topic, canonical alias etc. (Optional).
|
||||
include_all_networks:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether or not to include all known networks/protocols from
|
||||
application services on the homeserver. Defaults to false.
|
||||
example: false
|
||||
third_party_instance_id:
|
||||
type: string
|
||||
description: |-
|
||||
The specific third party network/protocol to request from the
|
||||
homeserver. Can only be used if ``include_all_networks`` is false.
|
||||
example: "irc"
|
||||
example: {
|
||||
"limit": 10, "filter": {"generic_search_term": "foo"}}
|
||||
"limit": 10,
|
||||
"filter": {
|
||||
"generic_search_term": "foo"
|
||||
},
|
||||
"include_all_networks": false,
|
||||
"third_party_instance_id": "irc"
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: A list of the rooms on the server.
|
||||
|
|
|
@ -73,7 +73,7 @@ paths:
|
|||
$ref: definitions/errors/error.yaml
|
||||
"/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retreive Matrix-side portals rooms leading to a third party location.
|
||||
summary: Retrieve Matrix-side portals rooms leading to a third party location.
|
||||
description: |-
|
||||
Requesting this endpoint with a valid protocol name results in a list
|
||||
of successful mapping results in a JSON array. Each result contains
|
||||
|
@ -151,7 +151,7 @@ paths:
|
|||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retreive an array of third party network locations from a Matrix room
|
||||
Retrieve an array of third party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
security:
|
||||
|
@ -181,7 +181,7 @@ paths:
|
|||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retreive an array of third party users from a Matrix User ID.
|
||||
Retrieve an array of third party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
security:
|
||||
- accessToken: []
|
||||
|
|
|
@ -49,6 +49,20 @@ paths:
|
|||
A pagination token from a previous call to this endpoint to fetch more
|
||||
rooms.
|
||||
x-example: "GetMoreRoomsTokenHere"
|
||||
- in: query
|
||||
name: include_all_networks
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether or not to include all networks/protocols defined by application
|
||||
services on the homeserver. Defaults to false.
|
||||
x-example: false
|
||||
- in: query
|
||||
name: third_party_instance_id
|
||||
type: string
|
||||
description: |-
|
||||
The specific third party network/protocol to request from the homeserver.
|
||||
Can only be used if ``include_all_networks`` is false.
|
||||
x-example: "irc"
|
||||
responses:
|
||||
200:
|
||||
description: The public room list for the homeserver.
|
||||
|
|
1
changelogs/client_server/newsfragments/1554.feature
Normal file
1
changelogs/client_server/newsfragments/1554.feature
Normal file
|
@ -0,0 +1 @@
|
|||
Add third party network room directories, as provided by application services.
|
|
@ -180,6 +180,27 @@ this request (e.g. to join a room alias).
|
|||
{{query_room_as_http_api}}
|
||||
|
||||
|
||||
Third party networks
|
||||
++++++++++++++++++++
|
||||
|
||||
Application services may declare which protocols they support via their registration
|
||||
configuration for the homeserver. These networks are generally for third party services
|
||||
such as IRC that the application service is managing. Application services may populate
|
||||
a Matrix room directory for their registered protocols, as defined in the Client-Server
|
||||
API Extensions.
|
||||
|
||||
Each protocol may have several "locations" (also known as "third party locations" or "3PLs").
|
||||
A location within a protocol is a place in the third party network, such as an IRC channel.
|
||||
Users of the third party network may also be represented by the application service.
|
||||
|
||||
Locations and users can be searched by fields defined by the application service, such
|
||||
as by display name or other attribute. When clients request the homeserver to search
|
||||
in a particular "network" (protocol), the search fields will be passed along to the
|
||||
application service for filtering.
|
||||
|
||||
{{protocols_as_http_api}}
|
||||
|
||||
|
||||
HTTP APIs
|
||||
+++++++++
|
||||
|
||||
|
@ -198,6 +219,9 @@ Application services can use a more powerful version of the
|
|||
client-server API by identifying itself as an application service to the
|
||||
homeserver.
|
||||
|
||||
Endpoints defined in this section MUST be supported by homeservers in the
|
||||
client-server API as accessible only by application services.
|
||||
|
||||
Identity assertion
|
||||
++++++++++++++++++
|
||||
The client-server API infers the user ID from the ``access_token`` provided in
|
||||
|
@ -294,6 +318,15 @@ API MUST do so with a virtual user (provide a ``user_id`` via the query string).
|
|||
is expected that the application service use the transactions pushed to it to
|
||||
handle events rather than syncing with the user implied by ``sender_localpart``.
|
||||
|
||||
Application service room directories
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Application services can maintain their own room directories for their defined
|
||||
third party protocols. These room directories may be accessed by clients through
|
||||
additional parameters on the ``/publicRooms`` client-server endpoint.
|
||||
|
||||
{{appservice_room_directory_cs_http_api}}
|
||||
|
||||
Event fields
|
||||
~~~~~~~~~~~~
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue