You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
382 lines
17 KiB
ReStructuredText
382 lines
17 KiB
ReStructuredText
Unreleased changes
|
|
==================
|
|
|
|
- Changes to the API which will be backwards-compatible for clients:
|
|
|
|
- New endpoints:
|
|
|
|
- ``POST /user_directory/search``
|
|
(`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
|
|
- ``GET /rooms/{roomId}/event/{eventId}``
|
|
(`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
|
|
- ``POST /delete_devices``
|
|
(`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
|
|
|
|
- Sticker messages:
|
|
- Add sticker message event definition.
|
|
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
|
|
- Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``
|
|
(`#1364 <https://github.com/matrix-org/matrix-doc/pull/1364>`_).
|
|
- Add 'token' parameter to /keys/query endpoint
|
|
(`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
|
|
- Add the room visibility options for the room directory
|
|
(`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
|
|
- Add spec for ignoring users
|
|
(`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
|
|
- Add the ``/register/available`` endpoint for username availability
|
|
(`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
|
|
- Add ``allow_remote`` to the content repo to avoid routing loops
|
|
(`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
|
|
- Add report content API
|
|
(`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
|
|
- Document ``/logout/all`` endpoint
|
|
(`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
|
|
- Document `highlights` field in /search response
|
|
(`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
|
|
- Document the GET version of ``/login``
|
|
(`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
|
|
|
|
- Spec clarifications:
|
|
|
|
- Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions
|
|
to clarify that they relate to intended display size, as opposed to the
|
|
intrinsic size of the image file.
|
|
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
|
|
- Mark ``home_server`` return field for ``/login`` and ``/register``
|
|
endpoints as deprecated
|
|
(`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
|
|
- Fix response format of ``/keys/changes`` endpoint
|
|
(`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_).
|
|
- Clarify default values for some fields on the /search API
|
|
(`#1109 <https://github.com/matrix-org/matrix-doc/pull/1109>`_).
|
|
- Fix the representation of ``m.presence`` events
|
|
(`#1137 <https://github.com/matrix-org/matrix-doc/pull/1137>`_).
|
|
- Clarify that ``m.tag`` ordering is done with numbers, not strings
|
|
(`#1139 <https://github.com/matrix-org/matrix-doc/pull/1139>`_).
|
|
- Clarify that ``/account/whoami`` should consider application services
|
|
(`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
|
|
- Mark ``GET /rooms/{roomId}/members`` as requiring authentication
|
|
(`#1245 <https://github.com/matrix-org/matrix-doc/pull/1244>`_).
|
|
- Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages``
|
|
(`#1380 <https://github.com/matrix-org/matrix-doc/pull/1380>`_).
|
|
- Mark ``GET /presence/{userId}/status`` as requiring authentication
|
|
(`#1371 <https://github.com/matrix-org/matrix-doc/pull/1371>`_).
|
|
- Describe ``StateEvent`` for ``/createRoom``
|
|
(`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
|
|
- Describe how the ``reason`` is handled for kicks/bans
|
|
(`#1362 <https://github.com/matrix-org/matrix-doc/pull/1362>`_).
|
|
- Clarify that clients must leave rooms before forgetting them
|
|
(`#1378 <https://github.com/matrix-org/matrix-doc/pull/1378>`_).
|
|
- Clarify the request and result types on ``/search``
|
|
(`#1381 <https://github.com/matrix-org/matrix-doc/pull/1381>`_).
|
|
|
|
r0.3.0
|
|
======
|
|
|
|
- Breaking changes:
|
|
|
|
- Change the rule kind of ``.m.rule.contains_display_name`` from
|
|
``underride`` to ``override``. This works with all known clients
|
|
which support push rules, but any other clients implementing
|
|
the push rules API should be aware of this change. This
|
|
makes it simple to mute rooms correctly in the API
|
|
(`#373 <https://github.com/matrix-org/matrix-doc/pull/373>`_).
|
|
- Remove ``/tokenrefresh`` from the API
|
|
(`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
|
|
- Remove requirement that tokens used in token-based login be macaroons
|
|
(`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
|
|
- Move ``thumbnail_url`` and ``thumbnail_info`` members of json objects
|
|
for ``m.room.message`` events with msgtypes ``m.image``, ``m.file``
|
|
and ``m.location``, inside the ``info`` member, to match ``m.video``
|
|
events
|
|
(`#723 <https://github.com/matrix-org/matrix-doc/pull/723>`_).
|
|
|
|
- Changes to the API which will be backwards-compatible for clients:
|
|
|
|
- Add ``filename`` parameter to ``POST /_matrix/media/r0/upload``
|
|
(`#364 <https://github.com/matrix-org/matrix-doc/pull/364>`_).
|
|
- Document CAS-based client login and the use of ``m.login.token`` in
|
|
``/login`` (`#367 <https://github.com/matrix-org/matrix-doc/pull/367>`_).
|
|
- Make ``origin_server_ts`` a mandatory field of room events
|
|
(`#379 <https://github.com/matrix-org/matrix-doc/pull/370>`_).
|
|
- Add top-level ``account_data`` key to the responses to ``GET /sync`` and
|
|
``GET /initialSync``
|
|
(`#380 <https://github.com/matrix-org/matrix-doc/pull/380>`_).
|
|
- Add ``is_direct`` flag to ``POST /createRoom`` and invite member event.
|
|
Add 'Direct Messaging' module
|
|
(`#389 <https://github.com/matrix-org/matrix-doc/pull/389>`_).
|
|
- Add ``contains_url`` option to ``RoomEventFilter``
|
|
(`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
|
|
- Add ``filter`` optional query param to ``/messages``
|
|
(`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
|
|
- Add 'Send-to-Device messaging' module
|
|
(`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
|
|
- Add 'Device management' module
|
|
(`#402 <https://github.com/matrix-org/matrix-doc/pull/402>`_).
|
|
- Require that User-Interactive auth fallback pages call
|
|
``window.postMessage`` to notify apps of completion
|
|
(`#398 <https://github.com/matrix-org/matrix-doc/pull/398>`_).
|
|
- Add pagination and filter support to ``/publicRooms``. Change response to
|
|
omit fields rather than return ``null``. Add estimate of total number of
|
|
rooms in list.
|
|
(`#388 <https://github.com/matrix-org/matrix-doc/pull/388>`_).
|
|
- Allow guest accounts to use a number of endpoints which are required for
|
|
end-to-end encryption.
|
|
(`#751 <https://github.com/matrix-org/matrix-doc/pull/751>`_).
|
|
- Add key distribution APIs, for use with end-to-end encryption.
|
|
(`#894 <https://github.com/matrix-org/matrix-doc/pull/894>`_).
|
|
- Add ``m.room.pinned_events`` state event for rooms.
|
|
(`#1007 <https://github.com/matrix-org/matrix-doc/pull/1007>`_).
|
|
- Add mention of ability to send Access Token via an Authorization Header.
|
|
- Add ``guest_can_join`` parameter to ``POST /createRoom``
|
|
(`#1093 <https://github.com/matrix-org/matrix-doc/pull/1093>`_).
|
|
|
|
- New endpoints:
|
|
|
|
- ``GET /joined_rooms``
|
|
(`#999 <https://github.com/matrix-org/matrix-doc/pull/999>`_).
|
|
|
|
- ``GET /rooms/{roomId}/joined_members``
|
|
(`#999 <https://github.com/matrix-org/matrix-doc/pull/999>`_).
|
|
|
|
- ``GET /account/whoami``
|
|
(`#1063 <https://github.com/matrix-org/matrix-doc/pull/1063>`_).
|
|
|
|
- ``GET /media/{version}/preview_url``
|
|
(`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).
|
|
|
|
- Spec clarifications:
|
|
|
|
- Add endpoints and logic for invites and third-party invites to the federation
|
|
spec and update the JSON of the request sent by the identity server upon 3PID
|
|
binding
|
|
(`#997 <https://github.com/matrix-org/matrix-doc/pull/997>`_)
|
|
- Fix "membership" property on third-party invite upgrade example
|
|
(`#995 <https://github.com/matrix-org/matrix-doc/pull/995>`_)
|
|
- Fix response format and 404 example for room alias lookup
|
|
(`#960 <https://github.com/matrix-org/matrix-doc/pull/960>`_)
|
|
- Fix examples of ``m.room.member`` event and room state change,
|
|
and added a clarification on the membership event sent upon profile update
|
|
(`#950 <https://github.com/matrix-org/matrix-doc/pull/950>`_).
|
|
- Spell out the way that state is handled by ``POST /createRoom``
|
|
(`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
|
|
- Clarify the fields which are applicable to different types of push rule
|
|
(`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
|
|
- A number of clarifications to authentication
|
|
(`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
|
|
- Correct references to ``user_id`` which should have been ``sender``
|
|
(`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
|
|
- Correct inconsistent specification of ``redacted_because`` fields and their
|
|
values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
|
|
- Mark required fields in response objects as such
|
|
(`#394 <https://github.com/matrix-org/matrix-doc/pull/394>`_).
|
|
- Make ``m.notice`` description a bit harder in its phrasing to try to
|
|
dissuade the same issues that occurred with IRC
|
|
(`#750 <https://github.com/matrix-org/matrix-doc/pull/750>`_).
|
|
- ``GET /user/{userId}/filter/{filterId}`` requires authentication
|
|
(`#1003 <https://github.com/matrix-org/matrix-doc/pull/1003>`_).
|
|
- Add some clarifying notes on the behaviour of rooms with no
|
|
``m.room.power_levels`` event
|
|
(`#1026 <https://github.com/matrix-org/matrix-doc/pull/1026>`_).
|
|
- Clarify the relationship between ``username`` and ``user_id`` in the
|
|
``/register`` API
|
|
(`#1032 <https://github.com/matrix-org/matrix-doc/pull/1032>`_).
|
|
- Clarify rate limiting and security for content repository.
|
|
(`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).
|
|
|
|
r0.2.0
|
|
======
|
|
|
|
- Spec clarifications:
|
|
|
|
- Room aliases (`#337 <https://github.com/matrix-org/matrix-doc/pull/337>`_):
|
|
|
|
- Make it clear that ``GET /directory/room/{roomAlias}`` must work for
|
|
federated aliases.
|
|
|
|
- ``GET /directory/room/{roomAlias}`` cannot return a 409; the ``PUT``
|
|
endpoint can, however.
|
|
|
|
- Power levels:
|
|
|
|
- Clarify the defaults to be used for various fields of the
|
|
``m.room.power_levels`` event
|
|
(`#286 <https://github.com/matrix-org/matrix-doc/pull/286>`_,
|
|
`#341 <https://github.com/matrix-org/matrix-doc/pull/341>`_).
|
|
|
|
- Add suggestions for mapping of names to power levels
|
|
(`#336 <https://github.com/matrix-org/matrix-doc/pull/336>`_).
|
|
|
|
- Clarify the room naming algorithm in certain edge cases
|
|
(`#351 <https://github.com/matrix-org/matrix-doc/pull/351>`_).
|
|
|
|
- Remove outdated references to the pre-r0 ``/events`` API, and clarify the
|
|
section on syncing
|
|
(`#352 <https://github.com/matrix-org/matrix-doc/pull/352>`_).
|
|
|
|
|
|
- Changes to the API which will be backwards-compatible for clients:
|
|
|
|
- New endpoints:
|
|
|
|
- ``POST /register/email/requestToken``
|
|
(`#343 <https://github.com/matrix-org/matrix-doc/pull/343>`_).
|
|
|
|
- ``POST /account/3pid/email/requestToken``
|
|
(`#346 <https://github.com/matrix-org/matrix-doc/pull/346>`_).
|
|
|
|
- ``POST /account/password/email/requestToken``
|
|
(`#346 <https://github.com/matrix-org/matrix-doc/pull/346>`_).
|
|
|
|
- ``POST /account/deactivate``
|
|
(`#361 <https://github.com/matrix-org/matrix-doc/pull/361>`_).
|
|
|
|
- Updates to the Presence module
|
|
(`#278 <https://github.com/matrix-org/matrix-doc/pull/278>`_,
|
|
`#342 <https://github.com/matrix-org/matrix-doc/pull/342>`_):
|
|
|
|
- Remove unused ``free_for_chat`` presence state
|
|
- Add ``currently_active`` flag to the ``m.presence`` event and the ``GET
|
|
/presence/{userId}/status`` response.
|
|
- Make idle timeout the responsibility of the server
|
|
- Remove requirements on servers to propagate profile information via
|
|
``m.presence`` events.
|
|
|
|
- Add new predefined push rules
|
|
(`#274 <https://github.com/matrix-org/matrix-doc/pull/274>`_,
|
|
`#340 <https://github.com/matrix-org/matrix-doc/pull/340/files>`_).
|
|
|
|
- ``/sync`` should always return a ``prev_batch`` token
|
|
(`#345 <https://github.com/matrix-org/matrix-doc/pull/345>`_).
|
|
|
|
- add ``to`` parameter to ``GET /rooms/{roomId}/messages`` API
|
|
(`#348 <https://github.com/matrix-org/matrix-doc/pull/348>`_).
|
|
|
|
r0.1.0
|
|
======
|
|
|
|
This release includes the following changes since r0.0.1:
|
|
|
|
- Breaking changes to the API [#]_:
|
|
|
|
- ``POST /rooms/{roomId}/join`` no longer permits use of a room alias instead
|
|
of a room id. (``POST /join/{roomIdOrAlias}`` continues to allow either.)
|
|
- ``POST /account/3pid``: correct the name of the ``three_pid_creds``
|
|
parameter
|
|
- The "Push Rules" module no longer supports device-specific rules:
|
|
|
|
- ``GET /pushrules`` no longer returns a ``device`` property
|
|
- ``device/{profile_tag}`` is no longer a valid ``scope`` for push rules
|
|
- ``profile_tag`` is no longer a valid kind of condition on push rules.
|
|
|
|
(Device-specific push rules will be reintroduced in the future; in the
|
|
meantime, their specification has been moved to a `draft branch`__.)
|
|
|
|
__ https://matrix.org/speculator/spec/drafts%2Freinstate_device_push_rules/
|
|
|
|
- Changes to the API which will be backwards-compatible for clients:
|
|
|
|
- New endpoints:
|
|
|
|
- ``POST /logout``
|
|
- ``POST /rooms/{roomId}/unban``
|
|
- ``POST /rooms/{roomId}/kick``
|
|
- ``GET /pushers``
|
|
- ``GET /pushrules/{scope}/{kind}/{ruleId}/enabled``
|
|
(previously ``PUT``-only)
|
|
- ``GET`` and ``PUT /pushrules/{scope}/{kind}/{ruleId}/actions``
|
|
|
|
- Add ``third_party_signed`` parameter to ``POST /rooms/{roomId}/join``
|
|
- Add ``M_INVALID_USERNAME`` as valid response to ``POST /register``
|
|
- Add ``unread_notifications`` field to ``GET /sync`` response
|
|
- Add optional ``invite`` property to ``m.room.power_levels`` state event
|
|
- Add optional ``public_key`` and ``public_keys`` to
|
|
``m.room.third_party_invite`` state event
|
|
- Password-based ``/login`` may now use a third-party identifier instead of
|
|
a matrix user id.
|
|
|
|
- Spec clarifications
|
|
|
|
- Make the state diagram for room membership explicit
|
|
- Note that a user may not be invited to a room while banned
|
|
- Clarify the expected order of events in the response to
|
|
``GET /rooms/{roomId}/context/{eventId}``, as well as correcting the
|
|
example for that API
|
|
- Clarify the behaviour of the "Room History Visibility" module; in
|
|
particular, the behaviour of the ``shared`` history visibilty, and how
|
|
events at visibility boundaries should be handled
|
|
- Separate the "Room Previews" module from "Guest access"
|
|
- Reword the description of the ``profile_tag`` property in
|
|
``PUT /pushers/set``, and note that it is not mandatory.
|
|
|
|
|
|
.. [#] Our `versioning policy <../index.html#specification-versions>`_ would
|
|
strictly require that a breaking change be denoted by a new major
|
|
specification version. However we are not aware of any clients which
|
|
rely on the old behaviour here, nor server implementations which offer
|
|
it, so we have chosen to retain the r0 designation on this occasion.
|
|
|
|
r0.0.1
|
|
======
|
|
|
|
This release includes the following changes since r0.0.0:
|
|
|
|
- API changes:
|
|
- Added new ``/versions`` API
|
|
- ``/createRoom`` takes an optional ``invite_3pid`` parameter
|
|
- ``/publicRooms`` returns an ``avatar_url`` result
|
|
- The following APIs are now deprecated:
|
|
- ``/initialSync``
|
|
- ``/events``
|
|
- ``/events/:eventId``
|
|
- ``/rooms/:roomId/initialSync``
|
|
- Spec clarifications
|
|
- Document inter-version compatibility
|
|
- Document the parameters to the ``/user/:userId/filter`` API
|
|
- Document the ``next_batch`` parameter on ``/search``
|
|
- Document the membership states on ``m.room.member`` events
|
|
- Minor clarifications/corrections to:
|
|
- Guest access module
|
|
- Search module
|
|
- ``/login`` API
|
|
- ``/rooms/:roomId/send/:eventType/:txnId`` API
|
|
- ``/rooms/:roomId/context/:eventId`` API
|
|
|
|
r0.0.0
|
|
======
|
|
|
|
This is the first release of the client-server specification. It is largely a dump of what has currently been implemented, and there are several inconsistencies.
|
|
|
|
An upcoming minor release will deprecate many of these inconsistencies, and they will be removed in the next major release.
|
|
|
|
Since the draft stage, the following major changes have been made:
|
|
- /api/v1 and /v2_alpha path segments have been replaced with the major version of the release (i.e. 'r0').
|
|
- Some POST versions of APIs with both POST and PUT have been removed.
|
|
- The specification has been split into one specification per API. This is the client-server API. The server-server API can be found documented separately.
|
|
- All APIs are now documented using Swagger
|
|
- The following modules have been added:
|
|
- Content repository
|
|
- Instant messaging
|
|
- Push notification
|
|
- History visibility
|
|
- Search
|
|
- Invites based on third party identifiers
|
|
- Room tagging
|
|
- Guest access
|
|
- Client config
|
|
- The following APIs were added:
|
|
- ``/sync``
|
|
- ``/publicRooms``
|
|
- ``/rooms/{roomId}/forget``
|
|
- ``/admin/whois``
|
|
- ``/rooms/{roomId}/redact``
|
|
- ``/user/{userId}/filter``
|
|
- The following APIs have been significantly modified:
|
|
- Invitations now contain partial room state
|
|
- Invitations can now be rejected
|
|
- ``/directory``
|
|
- The following events have been added:
|
|
- ``m.room.avatar``
|
|
- Example signed json is included for reference
|
|
- Commentary on display name calculation was added
|