Merge pull request #1414 from matrix-org/anoa/third_party_cleanup

Clarification on third party fields

api/application-service/application_service.yaml

@@ -214,7 +214,7 @@ paths:
         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: queryMetadata
+      operationId: getProtocolMetadata
       parameters:
         - in: path
           name: protocol
@@ -270,7 +270,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the application
@@ -321,7 +321,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the application
@@ -446,4 +446,4 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml

api/application-service/definitions/protocol_metadata.yaml

@@ -13,6 +13,8 @@
 # limitations under the License.
 type: object
 description: Dictionary of supported third party protocols.
+additionalProperties:
+  $ref: protocol.yaml
 example: {
   "irc": {
     "user_fields": ["network", "nickname"],

api/application-service/definitions/user.yaml

@@ -27,5 +27,5 @@ properties:
     type: object
     example:
       "user": "jim"
-title: Location
+title: User
 type: object

api/client-server/third_party_lookup.yaml

@@ -34,7 +34,9 @@ paths:
         Fetches the overall metadata about protocols supported by the
         homeserver. Includes both the available protocols and all fields
         required for queries against each protocol.
-      operationId: queryMetadata
+      operationId: getProtocols
+      security:
+        - accessToken: []
       responses:
         200:
           description: The protocols supported by the homeserver.
@@ -45,7 +47,9 @@ paths:
       summary: Retrieve metadata about a specific protocol that the homeserver supports.
       description: |-
         Fetches the metadata from the homeserver about a particular third party protocol.
-      operationId: queryMetadata
+      operationId: getProtocolMetadata
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -80,6 +84,8 @@ paths:
         identifier. It should attempt to canonicalise the identifier as much
         as reasonably possible given the network type.
       operationId: queryLocationByProtocol
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -113,6 +119,8 @@ paths:
         Retrieve a Matrix User ID linked to a user on the third party service, given
         a set of user parameters.
       operationId: queryUserByProtocol
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -122,7 +130,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the AS to help identify the user.
@@ -146,12 +154,15 @@ paths:
         Retreive an array of third party network locations from a Matrix room
         alias.
       operationId: queryLocationByAlias
+      security:
+        - accessToken: []
       parameters:
         - in: query
           name: alias
           type: string
           description: The Matrix room alias to look up.
           required: true
+          x-example: "#matrix:matrix.org"
       responses:
         200:
           description: |-
@@ -172,12 +183,15 @@ paths:
       description: |-
         Retreive an array of third party users from a Matrix User ID.
       operationId: queryUserByID
+      security:
+        - accessToken: []
       parameters:
         - in: query 
           name: userid
           type: string
           description: The Matrix User ID to look up.
           required: true
+          x-example: "@bob:matrix.org"
       responses:
         200:
           description: |-
@@ -191,4 +205,4 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/errors/error.yaml
+            $ref: definitions/errors/error.yaml

api/openapi_extensions.md

@@ -0,0 +1,23 @@
+# OpenAPI Extensions
+
+For some functionality that is not directly provided by the OpenAPI v2
+specification, some extensions have been added that are to be consistent
+across the specification. The defined extensions are listed below. Extensions
+should not break parsers, however if extra functionality is required, aware
+parsers should be able to take advantage of the added syntax.
+
+## Extensible Query Parameters
+
+<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->
+
+If a unknown amount of query parameters can be added to a request, the `name`
+must be `fields...`, with the trailing ellipses representing the possibility
+of more fields.
+
+Example:
+
+```
+  - in: query
+    name: fields...
+    type: string
+```