Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-01-07 08:23:42 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

3PE lookup service

Browse source
This commit is contained in:
Andrew Morgan 2018-06-26 10:57:35 +01:00
parent c1b630e975
commit d73b247688
3 changed files with 401 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

391
api/application-service/application_service.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# 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.
@ -91,7 +92,13 @@ paths:
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
@ -147,7 +154,14 @@ paths:
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
@ -203,7 +217,378 @@ paths:
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
This API is called by the HS when it wants to present clients with
specific information about the various thirdparty networks that an AS
supports.
operationId: queryMetadata
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
examples:
application/json: {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
]
}
schema:
type: object
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:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix ID of a corresponding thirdparty user.
description: |-
This API is called by the HS in order to retrieve a Matrix ID linked
to a user on the external service, given a set of user parameters.
operationId: queryUserByProtocol
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: irc
- in: query
name: field1, field2...
type: string
description: |-
One or more custom fields that are passed to the AS to help identify the user.
responses:
200:
description: The Matrix IDs found with the given parameters.
examples:
application/json: [{
"userid": "@_gitter_jim:matrix.org",
"protocol": "gitter",
"fields": {
"user": "jim"
}
}]
schema:
type: array
description: Matched users.
items:
type: object
title: User
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:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portals rooms leading to a thirdparty 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
objects to represent the Matrix room or rooms that represent a portal
to this 3PN. Each has the Matrix room alias string, an identifier for
the particular 3PN protocol, and an object containing the
network-specific fields that comprise this identifier. It should
attempt to canonicalise the identifier as much as reasonably possible
given the network type.
operationId: queryLocationByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol used to communicate to the thirdparty network.
required: true
x-example: "irc"
- in: query
name: field1, field2...
type: string
description: |-
One or more custom fields that are passed to the AS to help
identify the thirdparty location.
responses:
200:
description: At least one portal room was found.
examples:
application/json: [{
"alias": "#freenode_#matrix:matrix.org",
"protocol": "irc",
"fields": {
"network": "freenode",
"channel": "#matrix"
}
}]
schema:
type: array
description: |-
Array of portal rooms leading to the requested thirdparty
location.
items:
type: object
title: Portal Room
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:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/location":
get:
summary: Reverse-lookup thirdparty locations given a Matrix room alias.
description: |-
Retreive an array of thirdparty network locations from a Matrix room
alias.
operationId: queryLocationByAlias
parameters:
- in: path
name: alias
type: string
description: The Matrix room alias to look up.
responses:
200:
description: |-
All found thirdparty locations. Same response format as the
forward lookup response.
examples:
application/json: [{
"alias": "#freenode_#matrix:matrix.org",
"protocol": "irc",
"fields": {
"network": "freenode",
"channel": "#matrix"
}
}]
schema:
type: array
description: Matched thirdparty locations.
items:
type: object
title: Location
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:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/user":
get:
summary: Reverse-lookup thirdparty users given a Matrix ID.
description: |-
Retreive an array of thirdparty users from a Matrix ID.
operationId: queryUserByID
paramters:
- in: path
name: userid
type: string
description: The Matrix ID to look up.
responses:
200:
description: |-
An array of thirdparty users.
examples:
application/json: [{
"userid": "@_gitter_jim:matrix.org",
"protocol": "gitter",
"fields": {
"user": "jim"
}
}]
schema:
type: array
description: Matched thirdparty users
items:
type: object
title: User
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:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
type: object
500:
description: There was a problem completing the request.
examples:
application/json: {
}
schema:
type: object

12
changelogs/client_server.rst
View file

@ -11,6 +11,18 @@ Unreleased changes
(`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
- ``POST /delete_devices``
(`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
- ``GET /thirdparty/protocols``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- ``GET /thirdparty/protocol/{protocol}``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- ``GET /thirdparty/location/{protocol}``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- ``GET /thirdparty/user/{protocol}``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- ``GET /thirdparty/location``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- ``GET /thirdparty/user``
(`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
- Sticker messages:
- Add sticker message event definition.

1
specification/targets.yaml
View file

@ -12,6 +12,7 @@ targets:
- { 1: modules.rst }
- { 2: feature_profiles.rst }
- { 2: "group:modules" } # reference a group of files
- { 1: thirdparty_lookup.rst }
version_label: "%CLIENT_RELEASE_LABEL%"
application_service:
files: