Skip to content

Latest commit

 

History

History
309 lines (254 loc) · 13.4 KB

client_server.rst

File metadata and controls

309 lines (254 loc) · 13.4 KB
Raw

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).
    • Remove /tokenrefresh from the API (#395).
    • Remove requirement that tokens used in token-based login be macaroons (#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).
  • Changes to the API which will be backwards-compatible for clients:
    • Add filename parameter to POST /_matrix/media/r0/upload (#364).
    • Document CAS-based client login and the use of m.login.token in /login (#367).
    • Make origin_server_ts a mandatory field of room events (#379).
    • Add top-level account_data key to the responses to GET /sync and GET /initialSync (#380).
    • Add is_direct flag to POST /createRoom and invite member event. Add 'Direct Messaging' module (#389).
    • Add contains_url option to RoomEventFilter (#390).
    • Add filter optional query param to /messages (#390).
    • Add 'Send-to-Device messaging' module (#386).
    • Add 'Device management' module (#402).
    • Require that User-Interactive auth fallback pages call window.postMessage to notify apps of completion (#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).
    • Allow guest accounts to use a number of endpoints which are required for end-to-end encryption. (#751).
    • Add key distribution APIs, for use with end-to-end encryption. (#894).
    • Add m.room.pinned_events state event for rooms. (#1007).
    • Add mention of ability to send Access Token via an Authorization Header.
    • Add guest_can_join parameter to POST /createRoom (#1093).
    • New endpoints:
      • GET /joined_rooms (#999).
      • GET /rooms/{roomId}/joined_members (#999).
      • GET /account/whoami (#1063).
      • GET /media/{version}/preview_url (#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)
    • Fix "membership" property on third-party invite upgrade example (#995)
    • Fix response format and 404 example for room alias lookup (#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).
    • Spell out the way that state is handled by POST /createRoom (#362).
    • Clarify the fields which are applicable to different types of push rule (#365).
    • A number of clarifications to authentication (#371).
    • Correct references to user_id which should have been sender (#376).
    • Correct inconsistent specification of redacted_because fields and their values (#378).
    • Mark required fields in response objects as such (#394).
    • Make m.notice description a bit harder in its phrasing to try to dissuade the same issues that occurred with IRC (#750).
    • GET /user/{userId}/filter/{filterId} requires authentication (#1003).
    • Add some clarifying notes on the behaviour of rooms with no m.room.power_levels event (#1026).
    • Clarify the relationship between username and user_id in the /register API (#1032).
    • Clarify rate limiting and security for content repository. (#1064).

r0.2.0

  • Spec clarifications:
    • Room aliases (#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, #341).
      • Add suggestions for mapping of names to power levels (#336).
    • Clarify the room naming algorithm in certain edge cases (#351).
    • Remove outdated references to the pre-r0 /events API, and clarify the section on syncing (#352).
  • Changes to the API which will be backwards-compatible for clients:
    • New endpoints:
      • POST /register/email/requestToken (#343).
      • POST /account/3pid/email/requestToken (#346).
      • POST /account/password/email/requestToken (#346).
      • POST /account/deactivate (#361).
    • Updates to the Presence module (#278, #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, #340).
    • /sync should always return a prev_batch token (#345).
    • add to parameter to GET /rooms/{roomId}/messages API (#348).

r0.1.0

This release includes the following changes since r0.0.1:

  • Breaking changes to the API1:
    • 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.

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

  1. Our versioning policy 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.↩