From 1045bc721d1270d0358383e49cd8e4ea919155a7 Mon Sep 17 00:00:00 2001
From: Maxime Dor <max@kamax.io>
Date: Wed, 15 Nov 2017 04:12:55 +0100
Subject: [PATCH] Document federation version endpoint

---
 api/server-server/version.yaml               | 53 ++++++++++++++++++++
 scripts/templating/matrix_templates/units.py |  1 +
 specification/server_server_api.rst          |  5 ++
 3 files changed, 59 insertions(+)
 create mode 100644 api/server-server/version.yaml

diff --git a/api/server-server/version.yaml b/api/server-server/version.yaml
new file mode 100644
index 00000000..19975529
--- /dev/null
+++ b/api/server-server/version.yaml
@@ -0,0 +1,53 @@
+# Copyright 2017 Kamax.io
+#
+# 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 Version API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/version":
+    get:
+      summary: Get the implementation name and version of this homeserver.
+      description: Get the implementation name and version of this homeserver.
+      responses:
+        200:
+          description:
+            The implementation name and version of this homeserver.
+          examples:
+            application/json: {
+                "server": {
+                  "name": "My_Homeserver_Implementation",
+                  "version": "ArbitraryVersionNumber"
+                }
+              }
+          schema:
+            type: object
+            properties:
+              server:
+                title: Server
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Arbitrary name that identify this implementation.
+                  version:
+                    type: string
+                    description: Version of this implementation. The version format depends on the implementation.
diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py
index 6eb58096..1540a7fd 100644
--- a/scripts/templating/matrix_templates/units.py
+++ b/scripts/templating/matrix_templates/units.py
@@ -40,6 +40,7 @@ HTTP_APIS = {
     os.path.join(matrix_doc_dir, "api/client-server"): "cs",
     os.path.join(matrix_doc_dir, "api/identity"): "is",
     os.path.join(matrix_doc_dir, "api/push-gateway"): "push",
+    os.path.join(matrix_doc_dir, "api/server-server"): "ss",
 }
 EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples")
 EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema")
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index b3e802c0..8ffe4e6a 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -92,6 +92,11 @@ default fallback port number of 8448.
 Homeservers may use SRV records to load balance requests between multiple TLS
 endpoints or to failover to another endpoint if an endpoint fails.
 
+Server implementation
+~~~~~~~~~~~~~~~~~~~~~~
+
+{{version_ss_http_api}}
+
 Retrieving Server Keys
 ~~~~~~~~~~~~~~~~~~~~~~