Split out and fix the /server and /query key APIs

api/server-server/keys_query.yaml

@@ -23,23 +23,6 @@ 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"
   "/query/{serverName}/{keyId}":
     get:
       summary: Retreive a server key
@@ -100,20 +83,16 @@ paths:
                   name: ServerName
                   description: The server names to query
                   additionalProperties:
-                    type: array
-                    name: ServerKey
+                    type: object
+                    title: Query Criteria
                     description: The server keys to query
-                    items:
-                      type: object
-                      title: Query Criteria
-                      description: The query criteria
-                      properties:
-                        minimum_valid_until_ts:
-                          type: integer
-                          format: int64
-                          description: Minimum Valid Until MS
-                          required: true # TODO: Verify
-                          x-example: 1234567890
+                    properties:
+                      minimum_valid_until_ts:
+                        type: integer
+                        format: int64
+                        description: Minimum Valid Until MS
+                        required: true # TODO: Verify
+                        example: 1234567890
       responses:
         200:
           description: The keys for the server

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"

specification/server_server_api.rst

@@ -167,50 +167,8 @@ If a server goes offline intermediate notary servers should continue to return
 the last response they received from that server so that the signatures of old
 events sent by that server can still be checked.
 
-==================== =================== ======================================
- Key                  Type                Description
-==================== =================== ======================================
-``server_name``      String              DNS name of the homeserver.
-``verify_keys``      Object              Public keys of the homeserver for
-                                         verifying digital signatures.
-``old_verify_keys``  Object              The public keys that the server used
-                                         to use and when it stopped using them.
-``signatures``       Object              Digital signatures for this object
-                                         signed using the ``verify_keys``.
-``tls_fingerprints`` Array of Objects    Hashes of X.509 TLS certificates used
-                                         by this server encoded as `Unpadded Base64`_.
-``valid_until_ts``   Integer             POSIX timestamp when the list of valid
-                                         keys should be refreshed.
-==================== =================== ======================================
-
+{{keys_server_ss_http_api}}
 
-.. code:: json
-
-    {
-        "old_verify_keys": {
-            "ed25519:auto1": {
-                "expired_ts": 922834800000,
-                "key": "Base+64+Encoded+Old+Verify+Key"
-            }
-        },
-        "server_name": "example.org",
-        "signatures": {
-            "example.org": {
-                "ed25519:auto2": "Base+64+Encoded+Signature"
-            }
-        },
-        "tls_fingerprints": [
-            {
-                "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
-            }
-        ],
-        "valid_until_ts": 1052262000000,
-        "verify_keys": {
-            "ed25519:auto2": {
-                "key": "Base+64+Encoded+Signature+Verification+Key"
-            }
-        }
-    }
 
 Querying Keys Through Another Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -233,7 +191,7 @@ This API can return keys for servers that are offline by using cached responses
 taken from when the server was online. Keys can be queried from multiple
 servers to mitigate against DNS spoofing.
 
-{{keys_ss_http_api}}
+{{keys_query_ss_http_api}}
 
 Version 1
 +++++++++