Merge branch 'master' into hs/dns-to-be-hostname

.circleci/config.yml

@@ -0,0 +1,64 @@
+gendoc: &gendoc
+  name: Generate the docs
+  command: |
+    source /env/bin/activate
+    scripts/gendoc.py
+
+genswagger: &genswagger
+  name: Generate the swagger
+  command: |
+    source /env/bin/activate
+    scripts/dump-swagger.py
+
+buildswaggerui: &buildswaggerui
+  name: Build Swagger UI
+  command: |
+    ls scripts/
+    mkdir -p api/client-server
+    git clone https://github.com/matrix-org/swagger-ui swagger-ui
+    cp -r swagger-ui/dist/* api/client-server/
+    mkdir -p api/client-server/json
+    cp scripts/swagger/api-docs.json api/client-server/json/
+    wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/content/swagger.css -O api/client-server/swagger.css
+    wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
+    patch api/client-server/index.html swagger-ui.patch
+
+
+version: 2
+jobs:
+  build-docs:
+    docker:
+      - image: uhoreg/matrix-doc-build
+    steps:
+      - checkout
+      - run: *gendoc
+      - store_artifacts:
+          path: scripts/gen
+      - run:
+          name: "Doc build is available at:"
+          command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
+
+  build-swagger:
+    docker:
+      - image: uhoreg/matrix-doc-build
+    steps:
+      - checkout
+      - run: *genswagger
+      - run: *buildswaggerui
+      - store_artifacts:
+          path: api/client-server/
+      - run:
+          name: "Swagger UI is available at:"
+          command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
+
+workflows:
+  version: 2
+
+  build-spec:
+    jobs:
+      - build-docs
+      - build-swagger
+
+notify:
+  webhooks:
+    - url: https://giles.cadair.com/circleci

.gitignore

@@ -1,7 +1,7 @@
 /api/node_modules
 /assets
 /assets.tar.gz
-/env
+/env*
 /scripts/gen
 /scripts/continuserv/continuserv
 /scripts/speculator/speculator
@@ -10,3 +10,4 @@
 /templating/out
 *.pyc
 *.swp
+_rendered.rst

.travis.yml

@@ -2,15 +2,15 @@ language: go
 go:
   - 1.8
 
-sudo: false
+sudo: required
 
 # we only need a single git commit
 git:
   depth: 1
 
-# test-and-build does the installation, so tell travis to skip the
+install:
-# installation step
+  - sudo apt-get update
-install: true
+  - sudo apt-get install python3 python3-dev
 
 script:
   - ./scripts/test-and-build.sh

CONTRIBUTING.rst

@@ -69,6 +69,41 @@ For such changes, please do just open a `pull request`_.
 
 .. _pull request: https://help.github.com/articles/about-pull-requests
 
+
+Adding to the changelog
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Currently only changes to the client-server API need to end up in a changelog. The
+other APIs are not yet stable and therefore do not have a changelog. Adding to the
+changelog can only be done after you've opened your pull request, so be sure to do
+that first. 
+
+The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
+form of "news fragments". The news fragments for the client-server API are stored
+under ``changelogs/client_server/newsfragments``. 
+
+To create a changelog entry, create a file named in the format ``prNumber.type`` in
+the ``newsfragments`` directory. The ``type`` can be one of the following:
+
+* ``new`` - Used when adding new endpoints. Please have the file contents be the
+  method and route being added, surrounded in RST code tags. For example: ``POST
+  /accounts/whoami``
+
+* ``feature`` - Used when adding backwards-compatible changes to the API.
+
+* ``clarification`` - Used when an area of the spec is being improved upon and does
+  not change or introduce any functionality.
+
+* ``breaking`` - Used when the change is not backwards compatible.
+
+* ``deprecation`` - Used when deprecating something
+
+All news fragments must have a brief summary explaining the change in the contents
+of the file.
+
+Changes that do not change the spec, such as changes to the build script, formatting,
+CSS, etc should not get a news fragment.
+
 Sign off
 --------
 

README.rst

@@ -41,9 +41,9 @@ specs and event schemas in this repository.
 Preparation
 -----------
 
-To use the scripts, it is best to create a Python 2.x virtualenv as follows::
+To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
 
-  virtualenv env
+  virtualenv -p python3 env
   env/bin/pip install -r scripts/requirements.txt
 
 (Benjamin Synders has contributed a script for `Nix`_ users, which can be

api/application-service/application_service.yaml

@@ -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.
@@ -29,8 +30,8 @@ paths:
     put:
       summary: Send some events to the application service.
       description: |-
-        This API is called by the HS when the HS wants to push an event (or
+        This API is called by the homeserver when it wants to push an event
-        batch of events) to the AS.
+        (or batch of events) to the application service.
       operationId: sendTransaction
       parameters:
         - in: path
@@ -47,33 +48,33 @@ paths:
           schema:
             type: object
             example: {
-                "events": [
+              "events": [
-                  {
+                {
-                    "age": 32,
+                  "age": 32,
-                    "content": {
+                  "content": {
-                        "body": "incoming message",
+                      "body": "incoming message",
-                        "msgtype": "m.text"
+                      "msgtype": "m.text"
-                    },
-                    "event_id": "$14328055551tzaee:localhost",
-                    "origin_server_ts": 1432804485886,
-                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                    "type": "m.room.message",
-                    "user_id": "@bob:localhost"
                   },
-                  {
+                  "event_id": "$14328055551tzaee:localhost",
-                    "age": 1984,
+                  "origin_server_ts": 1432804485886,
-                    "content": {
+                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                        "body": "another incoming message",
+                  "type": "m.room.message",
-                        "msgtype": "m.text"
+                  "user_id": "@bob:localhost"
-                    },
+                },
-                    "event_id": "$1228055551ffsef:localhost",
+                {
-                    "origin_server_ts": 1432804485886,
+                  "age": 1984,
-                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                  "content": {
-                    "type": "m.room.message",
+                      "body": "another incoming message",
-                    "user_id": "@bob:localhost"
+                      "msgtype": "m.text"
-                  }
+                  },
-                ]
+                  "event_id": "$1228055551ffsef:localhost",
-              }
+                  "origin_server_ts": 1432804485886,
+                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                  "type": "m.room.message",
+                  "user_id": "@bob:localhost"
+                }
+              ]
+            }
             description: "Transaction informations"
             properties:
               events:
@@ -88,10 +89,9 @@ paths:
           description: The transaction was processed successfully.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
-
   "/rooms/{roomAlias}":
     get:
       summary: Query if a room alias should exist on the application service.
@@ -119,7 +119,7 @@ paths:
             before responding.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
         401:
@@ -128,29 +128,29 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
           examples:
             application/json: {
-                "errcode": "M_FORBIDDEN"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: |-
             The application service indicates that this room alias does not exist.
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
   "/users/{userId}":
     get:
       summary: Query if a user should exist on the application service.
@@ -175,7 +175,7 @@ paths:
             service MUST create the user using the client-server API.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
         401:
@@ -184,26 +184,266 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
           examples:
             application/json: {
-                "errcode": "M_FORBIDDEN"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: |-
             The application service indicates that this user does not exist.
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/errors/error.yaml
+  "/_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: queryMetadata
+      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: field1, field2...
+          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: field1, field2...
+          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

api/application-service/definitions/location.yaml

@@ -0,0 +1,30 @@
+# 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.
+properties:
+  alias:
+    description: An alias for a matrix room.
+    type: string
+    example: "#freenode_#matrix:matrix.org"
+  protocol:
+    description: The protocol ID that the third party location is a part of.
+    type: string
+    example: irc
+  fields:
+    description: Information used to identify this third party location.
+    type: object
+    example:
+      "network": "freenode"
+      "channel": "#matrix"
+title: Location
+type: object

api/application-service/definitions/location_batch.yaml

@@ -0,0 +1,17 @@
+# 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.
+type: array
+description: List of matched third party locations.
+items:
+  $ref: location.yaml

api/application-service/definitions/protocol.yaml

@@ -0,0 +1,79 @@
+# 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.
+properties:
+  user_fields:
+    description: Fields used to identify a third party 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.
+    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.
+    type: string
+    example: "mxc://example.org/aBcDeFgH"
+  field_types:
+    title: Field Types
+    description: All location or user fields should have an entry here.
+    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
+    example: {
+      "network": {
+        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
+        "placeholder": "irc.example.org"
+      },
+      "nickname": {
+        "regexp": "[^\\s#]+",
+        "placeholder": "username"
+      },
+      "channel": {
+        "regexp": "#[^\\s]+",
+        "placeholder": "#foobar"
+      }
+    }
+  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.
+    type: array
+    items:
+      type: object
+      example: {
+        "desc": "Freenode",
+        "icon": "mxc://example.org/JkLmNoPq",
+        "fields": {
+          "network": "freenode.net",
+        }
+      }
+title: Protocol
+type: object

api/application-service/definitions/protocol_metadata.yaml

@@ -0,0 +1,66 @@
+# 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.
+type: object
+description: Dictionary of supported third party protocols.
+example: {
+  "irc": {
+    "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",
+        }
+      }
+    ]
+  },
+  "gitter": {
+    "user_fields": ["username"],
+    "location_fields": ["room"],
+    "field_types": {
+      "username": {
+        "regexp": "@[^\\s]+",
+        "placeholder": "@username"
+      },
+      "room": {
+        "regexp": "[^\\s]+\\/[^\\s]+",
+        "placeholder": "matrix-org/matrix-doc"
+      }
+    },
+    "instances": [
+      {
+        "desc": "Gitter",
+        "icon": "mxc://example.org/zXyWvUt",
+        "fields": {}
+      }
+    ]
+  }
+}

api/application-service/definitions/user.yaml

@@ -0,0 +1,31 @@
+# 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.
+
+# TODO: Change userid to user_id as a breaking change
+properties:
+  userid:
+    description: A Matrix User ID represting a third party user.
+    type: string
+    example: "@_gitter_jim:matrix.org"
+  protocol:
+    description: The protocol ID that the third party location is a part of.
+    type: string
+    example: gitter
+  fields:
+    description: Information used to identify this third party location.
+    type: object
+    example:
+      "user": "jim"
+title: Location
+type: object

api/application-service/definitions/user_batch.yaml

@@ -0,0 +1,17 @@
+# 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.
+type: array
+description: List of matched third party users.
+items:
+  $ref: user.yaml

api/client-server/administrative_contact.yaml

@@ -129,6 +129,8 @@ paths:
                 "errcode": "M_THREEPID_AUTH_FAILED",
                 "error": "The third party credentials could not be verified by the identity server."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - User data
   "/account/3pid/email/requestToken":

api/client-server/banning.yaml

@@ -61,7 +61,8 @@ paths:
                 description: The fully qualified user ID of the user being banned.
               reason:
                 type: string
-                description: The reason the user has been banned.
+                description: The reason the user has been banned. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:
@@ -82,6 +83,8 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to ban from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/unban":
@@ -133,5 +136,7 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to unban from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership

api/client-server/content-repo.yaml

@@ -72,7 +72,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}":
@@ -120,7 +120,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
@@ -175,7 +175,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
@@ -241,7 +241,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/preview_url":
@@ -296,6 +296,47 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/config":
+    get:
+      summary: Get the configuration for the content repository.
+      description: |-
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        **NOTE:** Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+      operationId: getConfig
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The public content repository configuration for the matrix server.
+          schema:
+            type: object
+            properties:
+              m.upload.size:
+                type: number
+                description: |- 
+                  The maximum size an upload can be in bytes.
+                  Clients SHOULD use this as a guide when uploading content.
+                  If not listed or null, the size limit should be treated as unknown.
+          examples:
+            application/json: {
+               "m.upload.size": 50000000
+            }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+
       tags:
         - Media

api/client-server/create_room.yaml

@@ -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.
@@ -40,7 +41,7 @@ paths:
         0. A default ``m.room.power_levels`` event, giving the room creator
            (and not other members) permission to send state events.
         
-        1. Events set by ``presets``.
+        1. Events set by the ``preset``.
 
         2. Events listed in ``initial_state``, in the order that they are
            listed.
@@ -49,6 +50,16 @@ paths:
 
         4. Invite events implied by ``invite`` and ``invite_3pid``.
 
+        The available presets do the following with respect to room state:
+
+        ========================  ==============  ======================  ================  =========
+                 Preset           ``join_rules``  ``history_visibility``  ``guest_access``  Other
+        ========================  ==============  ======================  ================  =========
+        ``private_chat``          ``invite``      ``shared``              ``can_join``      
+        ``trusted_private_chat``  ``invite``      ``shared``              ``can_join``      All invitees are given the same power level as the room creator.
+        ``public_chat``           ``public``      ``shared``              ``forbidden``     
+        ========================  ==============  ======================  ================  =========
+
       operationId: createRoom
       security:
         - accessToken: []
@@ -142,7 +153,7 @@ paths:
                   room. The expected format of the state events are an object
                   with type, state_key and content keys set.
 
-                  Takes precedence over events set by ``presets``, but gets
+                  Takes precedence over events set by ``preset``, but gets
                   overriden by ``name`` and ``topic`` keys.
                 items:
                   type: object
@@ -163,20 +174,7 @@ paths:
                 enum: ["private_chat", "public_chat", "trusted_private_chat"]
                 description: |-
                   Convenience parameter for setting various default state events
-                  based on a preset. Must be either:
+                  based on a preset.
-
-                  ``private_chat`` =>
-                    ``join_rules`` is set to ``invite``.
-                    ``history_visibility`` is set to ``shared``.
-
-                  ``trusted_private_chat`` =>
-                      ``join_rules`` is set to ``invite``.
-                      ``history_visibility`` is set to ``shared``.
-                      All invitees are given the same power level as the room creator.
-
-                  ``public_chat``: =>
-                      ``join_rules`` is set to ``public``.
-                      ``history_visibility`` is set to ``shared``.
               is_direct:
                 type: boolean
                 description: |-
@@ -218,6 +216,8 @@ paths:
               invalid: for example, the user's ``power_level`` is set below
               that necessary to set the room name (``errcode`` set to
               ``M_INVALID_ROOM_STATE``).
+          schema:
+            "$ref": "definitions/errors/error.yaml"
 
       tags:
         - Room creation

api/client-server/definitions/errors/error.yaml

@@ -17,7 +17,9 @@ properties:
   errcode:
     type: string
     description: An error code.
+    example: M_UNKNOWN
   error:
     type: string
     description: A human-readable error message.
+    example: An unknown error occurred
 required: ["errcode"]

api/client-server/definitions/errors/rate_limited.yaml

@@ -0,0 +1,32 @@
+# 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.
+$ref: error.yaml
+type: object
+description: The rate limit was reached for this request
+properties:
+  errcode:
+    type: string
+    description: The M_LIMIT_EXCEEDED error code
+    example: M_LIMIT_EXCEEDED
+  error:
+    type: string
+    description: A human-readable error message.
+    example: Too many requests
+  retry_after_ms:
+    type: integer
+    description: |-
+      The amount of time in milliseconds the client should wait
+      before trying the request again.
+    example: 2000
+required: ["errcode"]

api/client-server/directory.yaml

@@ -68,6 +68,8 @@ paths:
                 "errcode": "M_UNKNOWN",
                 "error": "Room alias #monkeys:matrix.org already exists."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     get:
@@ -118,6 +120,8 @@ paths:
                 "errcode": "M_NOT_FOUND",
                 "error": "Room alias #monkeys:matrix.org not found."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     delete:

api/client-server/inviting.yaml

@@ -93,9 +93,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership

api/client-server/joining.yaml

@@ -110,10 +110,12 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/join/{roomIdOrAlias}":
@@ -143,6 +145,15 @@ paths:
           description: The room identifier or alias to join.
           required: true
           x-example: "#monkeys:matrix.org"
+        - in: query
+          type: array
+          items:
+            type: string
+          name: server_name
+          description: |-
+            The servers to attempt to join the room through. One of the servers
+            must be participating in the room.
+          x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
           name: third_party_signed
           schema:
@@ -206,9 +217,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership

api/client-server/kicking.yaml

@@ -34,6 +34,10 @@ paths:
         Kick a user from the room.
 
         The caller must have the required power level in order to perform this operation.
+        
+        Kicking a user adjusts the target member's membership state to be ``leave`` with an
+        optional ``reason``. Like with other membership changes, a user can directly adjust
+        the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
       operationId: kick
       security:
         - accessToken: []
@@ -59,7 +63,9 @@ paths:
                 description: The fully qualified user ID of the user being kicked.
               reason:
                 type: string
-                description: The reason the user has been kicked.
+                description: |-
+                  The reason the user has been kicked. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:
@@ -81,5 +87,7 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to kick from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership

api/client-server/leaving.yaml

@@ -64,7 +64,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/forget":
@@ -78,8 +78,8 @@ paths:
         for this room. If all users on a homeserver forget a room, the room is
         eligible for deletion from that homeserver.
 
-        If the user is currently joined to the room, they will implicitly leave
+        If the user is currently joined to the room, they must leave the room
-        the room as part of this API call.
+        before calling this API.
       operationId: forgetRoom
       security:
         - accessToken: []
@@ -99,9 +99,18 @@ paths:
               }
           schema:
             type: object
+        400:
+          description: The user has not left the room
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN",
+              "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership

api/client-server/list_public_rooms.yaml

@@ -59,6 +59,8 @@ paths:
               "errcode": "M_NOT_FOUND",
               "error": "Room not found"
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
     put:
       summary: Sets the visibility of a room in the room directory
       description: |-
@@ -107,6 +109,8 @@ paths:
               "errcode": "M_NOT_FOUND",
               "error": "Room not found"
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
   "/publicRooms":
     get:
       summary: Lists the public rooms on the server.

api/client-server/login.yaml

@@ -61,7 +61,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Session management
     post:
@@ -167,15 +167,19 @@ paths:
                   "errcode": "M_UNKNOWN",
                   "error": "Bad login type."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         403:
           description: |-
             The login attempt failed. For example, the password may have been incorrect.
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Session management

api/client-server/message_pagination.yaml

@@ -107,6 +107,7 @@ paths:
                 items:
                   type: object
                   title: RoomEvent
+                  "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
           examples:
             application/json: {
                 "start": "t47429-4392820_219380_26003_2265",

api/client-server/presence.yaml

@@ -75,7 +75,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Presence
     get:
@@ -83,6 +83,8 @@ paths:
       description: |-
         Get the given user's presence state.
       operationId: getPresence
+      security:
+        - accessToken: []
       parameters:
         - in: path
           type: string
@@ -121,6 +123,17 @@ paths:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        403:
+          description: You are not allowed to see this user's presence status.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You are not allowed to see their presence"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Presence
   "/presence/list/{userId}":
@@ -176,7 +189,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Presence
     get:

api/client-server/profile.yaml

@@ -67,7 +67,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
     get:
@@ -141,7 +141,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
     get:

api/client-server/pusher.yaml

@@ -228,10 +228,10 @@ paths:
                 "errcode": "M_MISSING_PARAM"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Push notifications

api/client-server/pushrules.yaml

@@ -438,11 +438,11 @@ paths:
                 "errcode": "M_UNKNOWN"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":

api/client-server/receipts.yaml

@@ -76,6 +76,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room participation

api/client-server/registration.yaml

@@ -177,6 +177,8 @@ paths:
                   "errcode": "M_USER_IN_USE",
                   "error": "Desired user ID is already taken."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         401:
           description: |-
             The homeserver requires additional authentication information.
@@ -185,7 +187,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/register/email/requestToken":
@@ -249,7 +251,7 @@ paths:
                 "error": "The specified address is already in use"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
   "/account/password":
     post:
       summary: "Changes a user's password."
@@ -296,7 +298,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/account/password/email/requestToken":
@@ -363,7 +365,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/register/available":
@@ -420,9 +422,11 @@ paths:
               "errcode": "M_USER_IN_USE",
               "error": "Desired user ID is already taken."
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data

api/client-server/search.yaml

@@ -74,7 +74,7 @@ paths:
                 properties:
                   room_events:
                     type: object
-                    title: "Room Events"
+                    title: Room Events Criteria
                     description: Mapping of category name to search criteria.
                     properties:
                       search_term:
@@ -103,7 +103,7 @@ paths:
                           The order in which to search for results.
                           By default, this is ``"rank"``.
                       event_context:
-                        title: "Event Context"
+                        title: Include Event Context
                         type: object
                         description: |-
                           Configures whether any context for the events
@@ -169,13 +169,13 @@ paths:
             properties:
               search_categories:
                 type: object
-                title: Categories
+                title: Result Categories
                 description: Describes which categories to search in and
                   their criteria.
                 properties:
                   room_events:
                     type: object
-                    title: Room Event Results
+                    title: Result Room Events
                     description: Mapping of category name to search criteria.
                     properties:
                       count:
@@ -227,6 +227,9 @@ paths:
                                   description: |-
                                     The historic profile information of the
                                     users that sent the events returned.
+
+                                    The ``string`` key is the user ID for which
+                                    the profile belongs to.
                                   additionalProperties:
                                     type: object
                                     title: User Profile
@@ -260,15 +263,24 @@ paths:
                           The current state for every room in the results.
                           This is included if the request had the
                           ``include_state`` key set with a value of ``true``.
+
+                          The ``string`` key is the room ID for which the ``State
+                          Event`` array belongs to.
                         additionalProperties:
                           type: array
                           title: Room State
                           items:
+                            type: object
                             "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
                       groups:
                         type: object
                         title: Groups
-                        description: Any groups that were requested.
+                        description: |-
+                          Any groups that were requested.
+
+                          The outer ``string`` key is the group key requested (eg: ``room_id``
+                          or ``sender``). The inner ``string`` key is the grouped value (eg: 
+                          a room's ID or a user's ID).
                         additionalProperties:
                           type: object
                           title: Group Key
@@ -355,6 +367,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Search

api/client-server/third_party_lookup.yaml

@@ -0,0 +1,194 @@
+# 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 Third Party Lookup API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/thirdparty/protocols":
+    get:
+      summary: Retrieve metadata about all protocols that a homeserver supports.
+      description: |-
+        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
+      responses:
+        200:
+          description: The protocols supported by the homeserver.
+          schema:
+            $ref: ../application-service/definitions/protocol_metadata.yaml
+  "/thirdparty/protocol/{protocol}":
+    get:
+      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
+      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.
+          schema:
+            $ref: ../application-service/definitions/protocol.yaml
+        404:
+          description: The protocol is unknown.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/errors/error.yaml
+  "/thirdparty/location/{protocol}":
+    get:
+      summary: Retreive 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
+        objects to represent the Matrix room or rooms that represent a portal
+        to this third party network. Each has the Matrix room alias string,
+        an identifier for the particular third party network 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 third party network.
+          required: true
+          x-example: irc
+        - in: query
+          name: searchFields
+          type: string
+          description: |-
+            One or more custom fields to help identify the third party
+            location.
+      responses:
+        200:
+          description: At least one portal room was found.
+          schema:
+            $ref: ../application-service/definitions/location_batch.yaml
+        404:
+          description: No portal rooms were found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/errors/error.yaml
+  "/thirdparty/user/{protocol}":
+    get:
+      summary: Retrieve the Matrix User ID of a corresponding third party user.
+      description: |-
+        Retrieve a Matrix User ID linked to a user on the third party 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 User IDs found with the given parameters.
+          schema:
+            $ref: ../application-service/definitions/user_batch.yaml
+        404:
+          description: The Matrix User ID was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/errors/error.yaml
+  "/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.
+          required: true
+      responses:
+        200:
+          description: |-
+            All found third party locations.
+          schema:
+            $ref: ../application-service/definitions/location_batch.yaml
+        404:
+          description: The Matrix room alias was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/errors/error.yaml
+  "/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.
+          required: true
+      responses:
+        200:
+          description: |-
+            An array of third party users.
+          schema:
+            $ref: ../application-service/definitions/user_batch.yaml
+        404:
+          description: The Matrix User ID was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/errors/error.yaml

api/client-server/third_party_membership.yaml

@@ -126,9 +126,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership

api/client-server/typing.yaml

@@ -82,6 +82,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room participation

api/client-server/users.yaml

@@ -95,6 +95,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data

api/client-server/voip.yaml

@@ -73,6 +73,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - VOIP

api/client-server/whoami.yaml

@@ -65,7 +65,7 @@ paths:
               "error": "Unrecognised access token."
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
         403:
           description:
             The appservice cannot masquerade as the user or has not registered them.
@@ -75,10 +75,10 @@ paths:
               "error": "Application service has not registered this user."
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data

api/server-server/definitions/edu.yaml

@@ -0,0 +1,40 @@
+# 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.
+
+# TODO: Address any concerns about this being inaccurate (flagged as such in the EDUs section)
+
+type: object
+title: Ephemeral Data Unit
+description: An ephemeral data unit
+example:
+  $ref: "../examples/edu.json"
+properties:
+  edu_type:
+    type: string
+    description: The type of ephemeral message.
+    example: "m.presence"
+    required: true
+  origin:
+    type: string
+    description: The server name sending the ephemeral message.
+    example: "matrix.org"
+    required: true
+  destination:
+    type: string
+    description: The server name receiving the ephemeral message.
+    example: "elsewhere.com"
+    required: true
+  content:
+    type: object
+    description: The content of the ephemeral message.

api/server-server/definitions/keys.yaml

@@ -0,0 +1,96 @@
+# 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.
+type: object
+title: Server Keys
+description: Server keys
+example:
+  $ref: "../examples/server_key.json"
+properties:
+  server_name:
+    type: string
+    description: DNS name of the homeserver.
+    required: true # TODO: Verify
+    example: "example.org"
+  verify_keys:
+    type: object
+    description: Public keys of the homeserver for verifying digital signatures.
+    required: true # TODO: Verify
+    additionalProperties:
+      type: object
+      title: Verify Key
+      example: {
+        "ed25519:auto2": {
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        key:
+          type: string
+          description: The key
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  old_verify_keys:
+    type: object
+    description: The public keys that the server used to use and when it stopped using them.
+    additionalProperties:
+      type: object
+      title: Old Verify Key
+      example: {
+        "ed25519:auto1": {
+          "expired_ts": 922834800000,
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        expired_ts:
+          type: integer
+          format: int64
+          description: The expiration time.
+          required: true
+          example: 922834800000
+        key:
+          type: string
+          description: The key.
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  signatures:
+    type: object
+    description: Digital signatures for this object signed using the ``verify_keys``.
+    additionalProperties:
+      type: object
+      title: Signed Server
+      example: {
+        "example.org": {
+          "ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      additionalProperties:
+        type: string
+        name: Encoded Signature Verification Key
+  tls_fingerprints:
+    type: array
+    description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_.
+    items:
+      type: object
+      title: TLS Fingerprint
+      properties:
+        sha256:
+          type: string
+          description: The encoded fingerprint.
+          example: Base+64+Encoded+SHA-256-Fingerprint
+  valid_until_ts:
+    type: integer
+    format: int64
+    description: POSIX timestamp when the list of valid keys should be refreshed.
+    example: 1052262000000

api/server-server/definitions/keys_query_response.yaml

@@ -0,0 +1,27 @@
+# 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.
+type: object
+description: Server keys
+example: {
+  "server_keys": [{
+    $ref: "../examples/server_key.json"
+  }]
+}
+properties:
+  server_keys:
+    type: array
+    title: Server Keys
+    description: The server keys.
+    items:
+      $ref: "keys.yaml"

api/server-server/definitions/pdu.yaml

@@ -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.
+type: object
+title: Persistent Data Unit
+description: A persistent data unit (event)
+example:
+  $ref: "../examples/pdu.json"
+allOf:
+  - $ref: "unsigned_pdu.yaml"
+  - type: object
+    properties:
+      hashes:
+        type: object
+        title: Event Hash
+        description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
+        example: {
+          "sha256": "thishashcoversallfieldsincasethisisredacted"
+        }
+        properties:
+          sha256:
+            type: string
+            description: The hash.
+            example: thishashcoversallfieldsincasthisisredacted
+        required: ['sha256']
+      signatures:
+        type: object
+        description: |-
+          Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_.
+        example: {
+          "example.com": {
+            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+          }
+        }
+        additionalProperties:
+          type: object
+          title: Server Signatures
+          additionalProperties:
+            type: string
+    required:
+      - hashes
+      - signatures

api/server-server/definitions/transaction.yaml

@@ -0,0 +1,35 @@
+# 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.
+type: object
+title: Transaction
+description: Transaction
+example:
+  $ref: "../examples/transaction.json"
+properties:
+  origin:
+    type: string
+    description: |-
+      The ``server_name`` of the homeserver sending this transaction.
+    example: "example.org"
+  origin_server_ts:
+    type: integer
+    format: int64
+    description: Timestamp in milliseconds on originating homeserver when this transaction started.
+    example: 1234567890
+  pdus:
+    type: array
+    description: List of persistent updates to rooms.
+    items:
+      $ref: "pdu.yaml"
+required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/unsigned_pdu.yaml

@@ -0,0 +1,118 @@
+# 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.
+type: object
+title: Unsigned Persistent Data Unit
+description: An unsigned persistent data unit (event)
+example:
+  $ref: "../examples/unsigned_pdu.json"
+properties:
+  room_id:
+    type: string
+    description: Room identifier.
+    example: "!abc123:matrix.org"
+  sender:
+    type: string
+    description: The ID of the user sending the event.
+    example: "@someone:matrix.org"
+  origin:
+    type: string
+    description: The ``server_name`` of the homeserver that created this event.
+    example: "matrix.org"    
+  origin_server_ts:
+    type: integer
+    format: int64
+    description: Timestamp in milliseconds on origin homeserver when this event was created.
+    example: 1234567890
+  type:
+    type: string
+    description: Event type
+    example: "m.room.message"
+  state_key:
+    type: string
+    description: |-
+      If this key is present, the event is a state event, and it will replace previous events
+      with the same ``type`` and ``state_key`` in the room state.
+    example: "my_key"
+  content:
+    type: object
+    description: The content of the event.
+    example: {"key": "value"}
+  prev_events:
+    type: array
+    description: |-
+      Event IDs and hashes of the most recent events in the room that the homeserver was aware
+      of when it made this event.
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash.
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  depth:
+    type: integer
+    description: The maximum depth of the ``prev_events``, plus one.
+    example: 12
+  auth_events:
+    type: array
+    description: Event IDs and hashes for the "auth events" of this event.
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash.
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  redacts:
+    type: string
+    description: For redaction events, the ID of the event being redacted.
+    example: "$def456:matrix.org"
+  unsigned:
+    type: object
+    description: Additional data added by the origin server but not covered by the ``signatures``.
+    example: {"key": "value"}
+required:
+  - room_id
+  - sender
+  - origin
+  - origin_server_ts
+  - type
+  - content
+  - prev_events
+  - depth
+  - auth_events

api/server-server/directory.yaml

@@ -1,4 +1,5 @@
 # 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.
@@ -14,7 +15,7 @@
 
 swagger: '2.0'
 info:
-  title: "Matrix Federation Query Directory API"
+  title: "Matrix Federation Query API"
   version: "1.0.0"
 host: localhost:8448
 schemes:

api/server-server/events.yaml

@@ -0,0 +1,93 @@
+# 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 Events API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/state/{roomId}":
+    get:
+      summary: Get all the state of a given room
+      description: |-
+        Retrieves a snapshot of the entire current state of the given room.
+      operationId: getRoomState
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get state for.
+          required: true
+          x-example: "!abc123:matrix.org"
+      responses:
+        200:
+          description: The room state for the room (kept under ``pdus``).
+          schema:
+            $ref: "definitions/transaction.yaml"
+  "/event/{eventId}":
+    get:
+      summary: Get a single event
+      description: |-
+        Retrieves a single event.
+      operationId: getEvent
+      parameters:
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to get.
+          required: true
+          x-example: "$abc123:matrix.org"
+      responses:
+        200:
+          description: A transaction containing a single PDU which is the event requested.
+          schema:
+            $ref: "definitions/transaction.yaml"
+  "/backfill/{roomId}":
+    get:
+      summary: Retrieves the events which precede the given event
+      description: |-
+        Retreives a sliding-window history of previous PDUs that occurred in the given room.
+        Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
+        are retrieved, up to the total number given by the ``limit``.
+      operationId: backfillRoom
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to backfill.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: query
+          name: v
+          type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
+          description: The event ID to backfill from.
+          required: true
+          x-example: "$abc123:matrix.org"
+        - in: query
+          name: limit
+          type: integer
+          description: The maximum number of events to retrieve.
+          required: true
+          x-example: 10
+      responses:
+        200:
+          description: A transaction containing the PDUs that preceded the given event(s).
+          schema:
+            $ref: "definitions/transaction.yaml"

api/server-server/examples/edu.json

@@ -0,0 +1,8 @@
+{
+    "edu_type": "m.presence",
+    "origin": "blue",
+    "destination": "orange",
+    "content": {
+        "key": "value"
+    }
+}

api/server-server/examples/pdu.json

@@ -0,0 +1,11 @@
+{
+    "$ref": "unsigned_pdu.json",
+    "hashes": {
+        "sha256": "thishashcoversallfieldsincasethisisredacted"
+    },
+    "signatures": {
+        "example.com": {
+            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+        }
+    }
+}

api/server-server/examples/server_key.json

@@ -0,0 +1,23 @@
+{
+    "server_name": "example.org",
+    "verify_keys": {
+        "ed25519:auto2": {
+        "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+    },
+    "old_verify_keys": {
+        "ed25519:auto1": {
+        "expired_ts": 922834800000,
+            "key": "Base+64+Encoded+Old+Verify+Key"
+        }
+    },
+    "signatures": {
+        "example.org": {
+        "ed25519:auto2": "Base+64+Encoded+Signature"
+        }
+    },
+    "tls_fingerprints": [{
+        "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
+    }],
+    "valid_until_ts": 1052262000000
+}

api/server-server/examples/transaction.json

@@ -0,0 +1,5 @@
+{
+    "origin": "matrix.org",
+    "origin_server_ts": 1234567890,
+    "pdus": [{"$ref": "pdu.json"}]
+}

api/server-server/examples/unsigned_pdu.json

@@ -0,0 +1,17 @@
+{
+    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
+    "sender": "@alice:example.com",
+    "origin": "example.com",
+    "event_id": "$a4ecee13e2accdadf56c1025:example.com",
+    "origin_server_ts": 1404838188000,
+    "type": "m.room.message",
+    "prev_events": [
+        [
+            "$af232176:example.org",
+            {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
+        ]
+    ],
+    "content": {
+        "key": "value"
+    }
+}

api/server-server/keys_query.yaml

@@ -0,0 +1,99 @@
+# 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 Key Exchange API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/key/v2
+produces:
+  - application/json
+paths:
+  "/query/{serverName}/{keyId}":
+    get:
+      summary: Retrieve a server key.
+      description: Retrieve a server key.
+      operationId: perspectivesKeyQuery
+      parameters:
+        - in: path
+          name: serverName
+          type: string
+          description: Server name.
+          required: true
+          x-example: matrix.org
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID.
+          required: true
+          x-example: TODO # No examples in spec so far
+        - in: query
+          name: minimum_valid_until_ts
+          type: integer
+          format: int64
+          description: Minimum Valid Until Milliseconds.
+          required: true # TODO: Verify 
+          x-example: 1234567890
+      responses:
+        200:
+          description: The keys for the server
+          schema:
+            $ref: "definitions/keys_query_response.yaml"
+  "/query":
+    post:
+      summary: Retrieve a server key
+      description: Retrieve a server key.
+      operationId: bulkPerspectivesKeyQuery
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            # TODO: Improve example
+            example: {
+              "server_keys": {
+                "{server_name}": {
+                  "{key_id}": {
+                    "minimum_valid_until_ts": 1234567890
+                  }
+                }
+              }
+            }
+            properties:
+              server_keys:
+                type: object
+                description: The query criteria.
+                additionalProperties:
+                  type: object
+                  name: ServerName
+                  description: The server names to query.
+                  additionalProperties:
+                    type: object
+                    title: Query Criteria
+                    description: The server keys to query.
+                    properties:
+                      minimum_valid_until_ts:
+                        type: integer
+                        format: int64
+                        description: Minimum Valid Until MS.
+                        example: 1234567890
+            required: ['server_keys']
+      responses:
+        200:
+          description: The keys for the server.
+          schema:
+            $ref: "definitions/keys_query_response.yaml"

api/server-server/keys_server.yaml

@@ -0,0 +1,42 @@
+# 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 Key Exchange API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/key/v2
+produces:
+  - application/json
+paths:
+  "/server/{keyId}":
+    get:
+      summary: Get the server's key
+      description: Get the server's key.
+      operationId: getServerKey
+      parameters:
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID
+          required: false
+          x-example: TODO # No examples in the spec so far
+      responses:
+        200:
+          description: The server's keys.
+          schema:
+            $ref: "definitions/keys.yaml"

api/server-server/query_general.yaml

@@ -0,0 +1,44 @@
+# 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.

api/server-server/third_party_invite.yaml

@@ -0,0 +1,190 @@
+# 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 Third Party Invites API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/exchange_third_party_invite/{roomId}":
+    put:
+      summary: Request a server to auth a third party invite event
+      description: |-
+        The receiving server will verify the partial ``m.room.member`` event
+        given in the request body. If valid, the receiving server will issue
+        an invite as per the `Inviting to a room`_ section before returning a
+        response to this request.
+      operationId: exchangeThirdPartyInvite
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to exchange a third party invite in
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: body
+          name: body
+          type: object
+          description: A partial ``m.room.member`` event
+          required: true
+          schema:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The event type. Must be ``m.room.member``
+                example: "m.room.member"
+              room_id:
+                type: string
+                description: |-
+                  The room ID the event is for. Must match the ID given in
+                  the path.
+                example: "!abc123:matrix.org"
+              sender:
+                type: string
+                description: |-
+                  The user ID of the user who sent the original ``m.room.third_party_invite``
+                  event.
+                example: "@joe:matrix.org"
+              state_key:
+                type: string
+                description: The user ID of the invited user
+                example: "@someone:example.org"
+              content:
+                type: object
+                description: The event content
+                title: Event Content
+                properties:
+                  membership:
+                    type: string
+                    description: The membership state. Must be ``invite``
+                    example: invite
+                  third_party_invite:
+                    type: object
+                    description: The third party invite
+                    properties:
+                      display_name:
+                        type: string
+                        description: |-
+                          A name which can be displayed to represent the user instead of their
+                          third party identifier.
+                        example: "alice"
+                      signed:
+                        type: object
+                        description: |-
+                          A block of content which has been signed, which servers can use to
+                          verify the event.
+                        properties:
+                          signatures:
+                            type: object
+                            description: The server signatures for this event.
+                            additionalProperties:
+                              type: object
+                              title: Server Signatures
+                              additionalProperties:
+                                type: string
+                            example: {
+                              "magic.forest": {
+                                "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                              }
+                            }
+                          mxid:
+                            type: string
+                            description: The invited matrix user ID
+                            example: "@alice:localhost"
+                          token:
+                            type: string
+                            description: The token used to verify the event
+                            example: abc123
+                        required: ['signatures', 'mxid', 'token']
+                        example: {
+                          "mxid": "@alice:localhost",
+                          "token": "abc123",
+                          "signatures": {
+                            "magic.forest": {
+                              "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                            }
+                          }
+                        }
+                    required: ['display_name', 'signed']
+                    example: {
+                      "display_name": "alice",
+                      "signed": {
+                        "mxid": "@alice:localhost",
+                        "token": "abc123",
+                        "signatures": {
+                          "magic.forest": {
+                            "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                          }
+                        }
+                      }
+                    }
+                required: ['membership', 'third_party_invite']
+                example: {
+                  "membership": "invite",
+                  "third_party_invite": {
+                    "display_name": "alice",
+                    "signed": {
+                      "mxid": "@alice:localhost",
+                      "token": "abc123",
+                      "signatures": {
+                        "magic.forest": {
+                          "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                        }
+                      }
+                    }
+                  }
+                }
+            required:
+              - type
+              - room_id
+              - sender
+              - state_key
+              - content
+          example: {
+            "type": "m.room.member",
+            "room_id": "!abc123:matrix.org",
+            "sender": "@joe:matrix.org",
+            "state_key": "@someone:example.org",
+            "content": {
+              "membership": "invite",
+              "third_party_invite": {
+                "display_name": "alice",
+                "signed": {
+                  "mxid": "@alice:localhost",
+                  "token": "abc123",
+                  "signatures": {
+                    "magic.forest": {
+                      "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                    }
+                  }
+                }
+              }
+            }
+          }
+      responses:
+        200:
+          description: The invite has been issued successfully.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+            description: An empty object
+            example: {}

api/server-server/transactions.yaml

@@ -0,0 +1,64 @@
+# 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 Transaction API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/send/{txnId}":
+    put:
+      summary: Send a transaction
+      description: |-
+        Push messages representing live activity to another server. The destination name
+        will be set to that of the receiving server itself. Each embedded PDU in the
+        transaction body will be processed.
+      operationId: sendTransaction
+      parameters:
+        - in: path
+          name: txnId
+          type: string
+          # TODO: "Overrides any ID given in the JSON body" - What does this mean?
+          description: |-
+            The transaction ID. Overrides any ID given in the JSON body.
+          required: true
+          x-example: TODO # No examples in the spec so far
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            allOf:
+              - $ref: "definitions/transaction.yaml"
+              - type: object
+                properties:
+                  edus:
+                    type: array
+                    description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
+                    items:
+                      $ref: "definitions/edu.yaml"
+          example: {
+            "$ref": "examples/transaction.json",
+            "edus": [{"$ref": "edu.json"}] # Relative to the examples directory
+          }
+      responses:
+        200:
+          # TODO: Spec this (and figure out what it is)
+          description: TODO

changelogs/README.md

@@ -0,0 +1,55 @@
+<!-- Note: This is a markdown file so the build script's RST processing doesn't grab it -->
+
+# Changelogs
+
+[Towncrier](https://github.com/hawkowl/towncrier) is used to manage the changelog and 
+keep it up to date. Because of this, updating a changelog is really easy.
+
+## How to update a changelog when releasing an API
+
+1. Ensure you're in your Python 3 virtual environment
+2. `cd` your way to the API you're releasing (eg: `cd changelogs/client_server`)
+3. Run `towncrier --version "r0.4.0" --name "client-server" --yes` substituting the 
+   variables as approprite. Note that `--name` is required although the value is ignored.
+4. Commit the changes and finish the release process.
+
+## How to prepare a changelog for a new API
+
+For this example, we're going to pretend that the `server_server` API doesn't exist.
+
+1. Create the file `changelogs/server_server.rst`
+2. Create the folder `changelogs/server_server`
+3. In the new folder, create a `pyproject.toml` file with these contents:
+   ```toml
+   [tool.towncrier]
+    filename = "../server_server.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true
+   ```
+4. Create a `.gitignore` in `changelogs/server_server/newsfragments` with the contents `!.gitignore`

changelogs/client_server.rst

@@ -1,66 +1,3 @@
-Unreleased changes
-==================
-
-- Changes to the API which will be backwards-compatible for clients:
-
-  - New endpoints:
-
-    - ``POST /user_directory/search``
-      (`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
-    - ``GET /rooms/{roomId}/event/{eventId}``
-      (`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
-    - ``POST /delete_devices``
-      (`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
-
-  - Sticker messages:
-    - Add sticker message event definition.
-    (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
-  - Document the GET version of ``/login``
-    (`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
-
-- Spec clarifications:
-
-  - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions
-    to clarify that they relate to intended display size, as opposed to the
-    intrinsic size of the image file.
-    (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
-  - Mark ``home_server`` return field for ``/login`` and ``/register``
-    endpoints as deprecated
-    (`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
-  - Fix response format of ``/keys/changes`` endpoint
-    (`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_).
-  - Clarify default values for some fields on the /search API
-    (`#1109 <https://github.com/matrix-org/matrix-doc/pull/1109>`_).
-  - Fix the representation of ``m.presence`` events
-    (`#1137 <https://github.com/matrix-org/matrix-doc/pull/1137>`_).
-  - Clarify that ``m.tag`` ordering is done with numbers, not strings
-    (`#1139 <https://github.com/matrix-org/matrix-doc/pull/1139>`_).
-  - Clarify that ``/account/whoami`` should consider application services
-    (`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
-  - Mark ``GET /rooms/{roomId}/members`` as requiring authentication
-    (`#1245 <https://github.com/matrix-org/matrix-doc/pull/1244>`_).
-  - Describe ``StateEvent`` for ``/createRoom``
-    (`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
-
-- Changes to the API which will be backwards-compatible for clients:
-
-  - Add 'token' parameter to /keys/query endpoint
-    (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
-  - Add the room visibility options for the room directory
-    (`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
-  - Add spec for ignoring users
-    (`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
-  - Add the ``/register/available`` endpoint for username availability
-    (`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
-  - Add ``allow_remote`` to the content repo to avoid routing loops
-    (`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
-  - Add report content API
-    (`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
-  - Document ``/logout/all`` endpoint
-    (`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
-  - Document `highlights` field in /search response
-    (`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
-
 r0.3.0
 ======
 

changelogs/client_server/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/client_server/newsfragments/1096.new

@@ -0,0 +1 @@
+``POST /user_directory/search``

changelogs/client_server/newsfragments/1097.clarification

@@ -0,0 +1 @@
+Mark ``home_server`` return field for ``/login`` and ``/register`` endpoints as deprecated

changelogs/client_server/newsfragments/1104.feature

@@ -0,0 +1 @@
+Add ``token`` parameter to the ``/keys/query`` endpoint

changelogs/client_server/newsfragments/1106.clarification

@@ -0,0 +1 @@
+Fix response format of ``/keys/changes`` endpoint

changelogs/client_server/newsfragments/1109.clarification

@@ -0,0 +1 @@
+Clarify default values for some fields on the ``/search`` API

changelogs/client_server/newsfragments/1110.new

@@ -0,0 +1 @@
+``GET /rooms/{roomId}/event/{eventId}``

changelogs/client_server/newsfragments/1137.clarification

@@ -0,0 +1 @@
+Fix the representation of ``m.presence`` events

changelogs/client_server/newsfragments/1139.clarification

@@ -0,0 +1 @@
+Clarify that ``m.tag`` ordering is done with numbers, not strings

changelogs/client_server/newsfragments/1141.feature

@@ -0,0 +1 @@
+Add the room visibility options for the room directory

changelogs/client_server/newsfragments/1142.feature

@@ -0,0 +1 @@
+Add spec for ignoring users

changelogs/client_server/newsfragments/1151.feature

@@ -0,0 +1 @@
+Add the ``/register/available`` endpoint for username availability

changelogs/client_server/newsfragments/1152.clarification

@@ -0,0 +1 @@
+Clarify that ``/account/whoami`` should consider application services

changelogs/client_server/newsfragments/1158.clarification

@@ -0,0 +1,3 @@
+Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions 
+to clarify that they relate to intended display size, as opposed to the 
+intrinsic size of the image file.

changelogs/client_server/newsfragments/1158.feature

@@ -0,0 +1 @@
+Add sticker messages

changelogs/client_server/newsfragments/1239.new

@@ -0,0 +1 @@
+``POST /delete_devices``

changelogs/client_server/newsfragments/1245.clarification

@@ -0,0 +1 @@
+Mark ``GET /rooms/{roomId}/members`` as requiring authentication

changelogs/client_server/newsfragments/1263.feature

@@ -0,0 +1 @@
+Document ``/logout/all`` endpoint

changelogs/client_server/newsfragments/1264.feature

@@ -0,0 +1 @@
+Add report content API

changelogs/client_server/newsfragments/1265.feature

@@ -0,0 +1 @@
+Add ``allow_remote`` to the content repo to avoid routing loops

changelogs/client_server/newsfragments/1274.feature

@@ -0,0 +1 @@
+Document `highlights` field in /search response

changelogs/client_server/newsfragments/1329.clarification

@@ -0,0 +1 @@
+Describe ``StateEvent`` for ``/createRoom``

changelogs/client_server/newsfragments/1353.new

@@ -0,0 +1 @@
+``GET /thirdparty/*`` Endpoints

changelogs/client_server/newsfragments/1361.feature

@@ -0,0 +1 @@
+Document the GET version of ``/login``

changelogs/client_server/newsfragments/1362.clarification

@@ -0,0 +1 @@
+Describe how the ``reason`` is handled for kicks/bans

changelogs/client_server/newsfragments/1364.feature

@@ -0,0 +1 @@
+Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``

changelogs/client_server/newsfragments/1365.feature

@@ -0,0 +1 @@
+Document the CORS/preflight headers

changelogs/client_server/newsfragments/1371.clarification

@@ -0,0 +1 @@
+Mark ``GET /presence/{userId}/status`` as requiring authentication

changelogs/client_server/newsfragments/1373.clarification

@@ -0,0 +1 @@
+Describe the rate limit error response schema

changelogs/client_server/newsfragments/1378.clarification

@@ -0,0 +1 @@
+Clarify that clients must leave rooms before forgetting them

changelogs/client_server/newsfragments/1379.clarification

@@ -0,0 +1 @@
+Document guest access in ``/createRoom`` presets

changelogs/client_server/newsfragments/1380.clarification

@@ -0,0 +1 @@
+Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages``

changelogs/client_server/newsfragments/1381.clarification

@@ -0,0 +1 @@
+Clarify the request and result types on ``/search``

changelogs/client_server/newsfragments/1397.feature

@@ -0,0 +1 @@
+Document message formats on ``m.text`` and ``m.emote`` messages

changelogs/client_server/newsfragments/1400.clarification

@@ -0,0 +1 @@
+Clarify some of the properties on the search result

changelogs/client_server/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../client_server.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

event-schemas/examples/m.room.message#m.emote

@@ -2,7 +2,9 @@
   "age": 242352,
   "content": {
     "body": "thinks this is an example emote",
-    "msgtype": "m.emote"
+    "msgtype": "m.emote",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "thinks <b>this</b> is an example emote"
   },
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/examples/m.room.message#m.text

@@ -2,7 +2,9 @@
   "age": 242352,
   "content": {
     "body": "This is an example text message",
-    "msgtype": "m.text"
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "<b>This is an example text message</b>"
   },
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/schema/m.room.message#m.emote

@@ -12,6 +12,16 @@ properties:
         enum:
           - m.emote
         type: string
+      format:
+        description: |-
+          The format used in the ``formatted_body``. Currently only
+          ``org.matrix.custom.html`` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the ``body``. This is required if ``format``
+          is specified.
+        type: string
     required:
       - msgtype
       - body

event-schemas/schema/m.room.message#m.text

@@ -12,6 +12,16 @@ properties:
         enum:
           - m.text
         type: string
+      format:
+        description: |-
+          The format used in the ``formatted_body``. Currently only
+          ``org.matrix.custom.html`` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the ``body``. This is required if ``format``
+          is specified.
+        type: string
     required:
       - msgtype
       - body

pyproject.toml

@@ -0,0 +1,9 @@
+[ tool.giles ]
+
+  [ tool.giles.circleci_artifacts.docs ]
+    url = "gen/index.html"
+    message = "Click details to preview the HTML documentation."
+
+  [ tool.giles.circleci_artifacts.swagger ]
+    url = "client-server/index.html"
+    message = "Click to preview the swagger build."