Specify some of the common concepts for Matrix in the index

See #2061
Fixes #1468
Fixes #1528

The section is not referenced by the specifications yet - they do a fairly good job of explaining it over and over. In future, it would be good to point all the references to the index.

api/server-server/keys_query.yaml

@@ -44,16 +44,18 @@ paths:
           type: string
           description: |-
             **Deprecated**. Servers should not use this parameter and instead
-            opt to return all keys, not just the requested one. The key ID to 
+            opt to return all keys, not just the requested one. The key ID to
             look up.
+
+            When excluded, the trailing slash on this endpoint is optional.
           required: false
           x-example: "ed25519:abc123"
         - in: query
           name: minimum_valid_until_ts
           type: integer
           format: int64
           description: |-
-            A millisecond POSIX timestamp in milliseconds indicating when the returned 
+            A millisecond POSIX timestamp in milliseconds indicating when the returned
             certificates will need to be valid until to be useful to the requesting server.
 
             If not supplied, the current time as determined by the notary server is used.
@@ -114,7 +116,7 @@ paths:
                         format: int64
                         description: |-
                           A millisecond POSIX timestamp in milliseconds indicating when
-                          the returned certificates will need to be valid until to be 
+                          the returned certificates will need to be valid until to be
                           useful to the requesting server.
 
                           If not supplied, the current time as determined by the notary

api/server-server/keys_server.yaml

@@ -51,6 +51,8 @@ paths:
             **Deprecated**. Servers should not use this parameter and instead
             opt to return all keys, not just the requested one. The key ID to
             look up.
+
+            When excluded, the trailing slash on this endpoint is optional.
           required: false
           x-example: "ed25519:abc123"
           deprecated: true

changelogs/server_server/newsfragments/2097.clarification

@@ -0,0 +1 @@
+Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested.

specification/index.rst

@@ -425,6 +425,42 @@ dedicated API.  The API is symmetrical to managing Profile data.
   Would it really be overengineered to use the same API for both profile &
   private user data, but with different ACLs?
 
+
+Common concepts
+---------------
+
+Various things are common throughout all of the Matrix APIs. They are
+documented here.
+
+Trailing slashes on API endpoints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless the endpoint is explicltly specified to have a trailing slash, the
+slash is optional. For example, an endpoint specified as ``/_matrix/example/``
+would require a trailing slash, however an endpoint specified as ``/_matrix/example``
+has an optional slash (can be excluded when making requests).
+
+Namespacing
+~~~~~~~~~~~
+
+Namespacing helps prevent conflicts between multiple applications and the specification
+itself. Where namespacing is used, ``m.`` prefixes are used by the specification to
+indicate that the field is controlled by the specification. Custom or non-specified
+namespaces used in the wild SHOULD use the Java package naming convention to prevent
+conflicts.
+
+As an example, event types are namespaced under ``m.`` in the specification however
+any client can send a custom event type, such as ``com.example.game.score`` without
+needing to put the event into the ``m.`` namespace.
+
+Timestamps
+~~~~~~~~~~
+
+Unless otherwise stated, timestamps are measured as milliseconds since the Unix epoch.
+Throughout the specification this may be referred to as POSIX, Unix, or just "time in
+milliseconds".
+
+
 .. _`room versions`:
 
 Room Versions