Specify some of the common concepts for Matrix in the index

See https://github.com/matrix-org/matrix-doc/pull/2061
Fixes https://github.com/matrix-org/matrix-doc/issues/1468
Fixes https://github.com/matrix-org/matrix-doc/issues/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.
pull/977/head
Travis Ralston 5 years ago
parent e1266b859f
commit b9c9396c11

@ -44,8 +44,10 @@ 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
@ -53,7 +55,7 @@ paths:
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

@ -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

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

@ -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

Loading…
Cancel
Save