Merge pull request #250 from matrix-org/daniel/versionsyo

Add /_matrix/versions to spec

api/client-server/versions.yaml

@@ -0,0 +1,41 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Versions API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client
+produces:
+  - application/json
+paths:
+  "/versions":
+    get:
+      summary: Gets the versions of the specification supported by the server.
+      description: |-
+        Gets the versions of the specification supported by the server.
+
+        Values will take the form ``rX.Y.Z``.
+
+        Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
+        i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
+      responses:
+        200:
+          description: The versions supported by the server.
+          examples:
+            application/json: |-
+              {
+                "versions": ["r0.0.1"]
+              }
+          schema:
+            type: object
+            properties:
+              versions:
+                type: array
+                description: The supported versions.
+                items:
+                  type: string
+                  description: The supported versions
+      tags:
+        - Server administration

specification/client_server_api.rst

@@ -106,6 +106,8 @@ Some API endpoints may allow or require the use of ``POST`` requests without a
 transaction ID. Where this is optional, the use of a ``PUT`` request is strongly
 recommended.
 
+{{versions_http_api}}
+
 Client Authentication
 ---------------------
 Most API endpoints require the user to identify themselves by presenting

specification/index.rst

@@ -36,3 +36,14 @@ Before we formally started releasing the specification, the last working copy
 we had can be found `here`__.
 
 .. __: https://matrix.org/docs/spec/legacy/
+
+Versioning
+----------
+
+The specifications are each versioned in the form ``rX.Y.Z``.
+
+Changes to ``X`` and ``Y`` should not be assumed to be compatible with any other version.
+
+For a fixed ``X`` and ``Y``, any ``Z`` should be assumed to be compatible with any lesser ``Z``.
+
+For example, it is safe to assume that a server which claims to implement ``r0.1.2`` supports ``r0.1.0``, but not vice-versa.