Skip to content

Commit c2ef38f

Browse files
zecakehzecakeh
authored
Document instance_id field of /thirdparty/protocols (matrix-org#2051)
Signed-off-by: Kévin Commaille <[email protected]>
1 parent dcb39c6 commit c2ef38f

File tree

9 files changed

+247
-174
lines changed

9 files changed

+247
-174
lines changed

‎changelogs/client_server/newsfragments/2051.clarification

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Document the `instance_id` field of `Protocol Instance` in the responses to
2+
`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.

‎data/api/application-service/definitions/protocol.yaml

+12-98
Original file line numberDiff line numberDiff line change
@@ -11,101 +11,15 @@
1111
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
14-
title: Protocol
15-
type: object
16-
properties:
17-
user_fields:
18-
description: |-
19-
Fields which may be used to identify a third-party user. These should be
20-
ordered to suggest the way that entities may be grouped, where higher
21-
groupings are ordered first. For example, the name of a network should be
22-
searched before the nickname of a user.
23-
type: array
24-
items:
25-
type: string
26-
description: Field used to identify a third-party user.
27-
example: ["network", "nickname"]
28-
location_fields:
29-
description: |-
30-
Fields which may be used to identify a third-party location. These should be
31-
ordered to suggest the way that entities may be grouped, where higher
32-
groupings are ordered first. For example, the name of a network should be
33-
searched before the name of a channel.
34-
type: array
35-
items:
36-
type: string
37-
description: Field used to identify a third-party location.
38-
example: ["network", "channel"]
39-
icon:
40-
description: A content URI representing an icon for the third-party protocol.
41-
type: string
42-
example: "mxc://example.org/aBcDeFgH"
43-
field_types:
44-
description: |-
45-
The type definitions for the fields defined in `user_fields` and
46-
`location_fields`. Each entry in those arrays MUST have an entry here.
47-
The `string` key for this object is the field name itself.
48-
49-
May be an empty object if no fields are defined.
50-
type: object
51-
additionalProperties:
52-
title: Field Type
53-
description: Definition of valid values for a field.
54-
type: object
55-
properties:
56-
regexp:
57-
description: |-
58-
A regular expression for validation of a field's value. This may be relatively
59-
coarse to verify the value as the application service providing this protocol
60-
may apply additional validation or filtering.
61-
type: string
62-
placeholder:
63-
description: A placeholder serving as a valid example of the field value.
64-
type: string
65-
required: ['regexp', 'placeholder']
66-
example: {
67-
"network": {
68-
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
69-
"placeholder": "irc.example.org"
70-
},
71-
"nickname": {
72-
"regexp": "[^\\s#]+",
73-
"placeholder": "username"
74-
},
75-
"channel": {
76-
"regexp": "#[^\\s]+",
77-
"placeholder": "#foobar"
78-
}
79-
}
80-
instances:
81-
description: |-
82-
A list of objects representing independent instances of configuration.
83-
For example, multiple networks on IRC if multiple are provided by the
84-
same application service.
85-
type: array
86-
items:
87-
type: object
88-
title: Protocol Instance
89-
properties:
90-
desc:
91-
type: string
92-
description: A human-readable description for the protocol, such as the name.
93-
example: "Freenode"
94-
icon:
95-
type: string
96-
description: |-
97-
An optional content URI representing the protocol. Overrides the one provided
98-
at the higher level Protocol object.
99-
example: "mxc://example.org/JkLmNoPq"
100-
fields:
101-
type: object
102-
description: Preset values for `fields` the client may use to search by.
103-
example: {
104-
"network": "freenode"
105-
}
106-
network_id:
107-
type: string
108-
description: A unique identifier across all instances.
109-
example: "freenode"
110-
required: ['desc', 'fields', 'network_id']
111-
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
14+
allOf:
15+
- $ref: protocol_base.yaml
16+
- type: object
17+
properties:
18+
instances:
19+
description: |-
20+
A list of objects representing independent instances of configuration.
21+
For example, multiple networks on IRC if multiple are provided by the
22+
same application service.
23+
type: array
24+
items:
25+
$ref: protocol_instance.yaml

‎data/api/application-service/definitions/protocol_base.yaml

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Copyright 2018 New Vector Ltd
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
title: Protocol
15+
type: object
16+
properties:
17+
user_fields:
18+
description: |-
19+
Fields which may be used to identify a third-party user. These should be
20+
ordered to suggest the way that entities may be grouped, where higher
21+
groupings are ordered first. For example, the name of a network should be
22+
searched before the nickname of a user.
23+
type: array
24+
items:
25+
type: string
26+
description: Field used to identify a third-party user.
27+
example: ["network", "nickname"]
28+
location_fields:
29+
description: |-
30+
Fields which may be used to identify a third-party location. These should be
31+
ordered to suggest the way that entities may be grouped, where higher
32+
groupings are ordered first. For example, the name of a network should be
33+
searched before the name of a channel.
34+
type: array
35+
items:
36+
type: string
37+
description: Field used to identify a third-party location.
38+
example: ["network", "channel"]
39+
icon:
40+
description: A content URI representing an icon for the third-party protocol.
41+
type: string
42+
example: "mxc://example.org/aBcDeFgH"
43+
field_types:
44+
description: |-
45+
The type definitions for the fields defined in `user_fields` and
46+
`location_fields`. Each entry in those arrays MUST have an entry here.
47+
The `string` key for this object is the field name itself.
48+
49+
May be an empty object if no fields are defined.
50+
type: object
51+
additionalProperties:
52+
title: Field Type
53+
description: Definition of valid values for a field.
54+
type: object
55+
properties:
56+
regexp:
57+
description: |-
58+
A regular expression for validation of a field's value. This may be relatively
59+
coarse to verify the value as the application service providing this protocol
60+
may apply additional validation or filtering.
61+
type: string
62+
placeholder:
63+
description: A placeholder serving as a valid example of the field value.
64+
type: string
65+
required: ['regexp', 'placeholder']
66+
example: {
67+
"network": {
68+
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
69+
"placeholder": "irc.example.org"
70+
},
71+
"nickname": {
72+
"regexp": "[^\\s#]+",
73+
"placeholder": "username"
74+
},
75+
"channel": {
76+
"regexp": "#[^\\s]+",
77+
"placeholder": "#foobar"
78+
}
79+
}
80+
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

‎data/api/application-service/definitions/protocol_instance.yaml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Copyright 2018 New Vector Ltd
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
type: object
15+
title: Protocol Instance
16+
properties:
17+
desc:
18+
type: string
19+
description: A human-readable description for the protocol, such as the name.
20+
example: "Freenode"
21+
icon:
22+
type: string
23+
description: |-
24+
An optional content URI representing the protocol. Overrides the one provided
25+
at the higher level Protocol object.
26+
example: "mxc://example.org/JkLmNoPq"
27+
fields:
28+
type: object
29+
description: Preset values for `fields` the client may use to search by.
30+
example: {
31+
"network": "freenode"
32+
}
33+
network_id:
34+
type: string
35+
description: A unique identifier across all instances.
36+
example: "freenode"
37+
required: ['desc', 'fields', 'network_id']

‎data/api/application-service/definitions/protocol_metadata.yaml

-70
This file was deleted.

‎data/api/client-server/definitions/protocol.yaml

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copyright 2018 New Vector Ltd
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
allOf:
15+
- $ref: ../../application-service/definitions/protocol_base.yaml
16+
- type: object
17+
properties:
18+
instances:
19+
description: |-
20+
A list of objects representing independent instances of configuration.
21+
For example, multiple networks on IRC if multiple are provided by the
22+
same application service.
23+
24+
The instances are modified by the homeserver from the response of
25+
[`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
26+
to include an `instance_id` to serve as a unique identifier for each
27+
instance on the homeserver.
28+
type: array
29+
items:
30+
allOf:
31+
- $ref: ../../application-service/definitions/protocol_instance.yaml
32+
- type: object
33+
properties:
34+
instance_id:
35+
type: string
36+
description: |-
37+
A unique identifier for this instance on the homeserver. This field is added
38+
to the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
39+
by the homeserver.
40+
41+
This is the identifier to use as the `third_party_instance_id` in a request to
42+
[`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms).
43+
example: "irc-freenode"

‎data/api/client-server/list_public_rooms.yaml

+4-1
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,9 @@ paths:
233233
description: |-
234234
The specific third-party network/protocol to request from the
235235
homeserver. Can only be used if `include_all_networks` is false.
236+
237+
This is the `instance_id` of a `Protocol Instance` returned by
238+
[`GET /_matrix/client/v3/thirdparty/protocols`](/client-server-api/#get_matrixclientv3thirdpartyprotocols).
236239
example: irc
237240
example: {
238241
"limit": 10,
@@ -244,7 +247,7 @@ paths:
244247
]
245248
},
246249
"include_all_networks": false,
247-
"third_party_instance_id": "irc"
250+
"third_party_instance_id": "irc-freenode"
248251
}
249252
description: Options for which rooms to return.
250253
required: true

0 commit comments

Comments
 (0)