From 873b0dcecfade192ef61f04796eec7d141ab0016 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Fri, 4 Dec 2015 11:09:35 +0000 Subject: [PATCH] Replace version numbers with release numbers --- CHANGELOG.rst | 2 +- api/client-server/account-data.yaml | 2 +- api/client-server/administrative_contact.yaml | 4 +- api/client-server/banning.yaml | 4 +- api/client-server/content-repo.yaml | 4 +- api/client-server/create_room.yaml | 4 +- api/client-server/directory.yaml | 4 +- api/client-server/filter.yaml | 4 +- api/client-server/guest_events.yaml | 4 +- api/client-server/inviting.yaml | 4 +- api/client-server/joining.yaml | 8 +- api/client-server/leaving.yaml | 4 +- api/client-server/list_public_rooms.yaml | 4 +- api/client-server/login.yaml | 4 +- api/client-server/message_pagination.yaml | 4 +- api/client-server/old_sync.yaml | 4 +- api/client-server/presence.yaml | 4 +- api/client-server/profile.yaml | 4 +- api/client-server/push_notifier.yaml | 2 +- api/client-server/pusher.yaml | 4 +- api/client-server/pushrules.yaml | 4 +- api/client-server/receipts.yaml | 4 +- api/client-server/registration.yaml | 4 +- api/client-server/room_send.yaml | 4 +- api/client-server/room_state.yaml | 4 +- api/client-server/rooms.yaml | 4 +- api/client-server/search.yaml | 6 +- api/client-server/sync.yaml | 4 +- api/client-server/tags.yaml | 2 +- api/client-server/third_party_membership.yaml | 4 +- api/client-server/typing.yaml | 4 +- api/client-server/voip.yaml | 4 +- drafts/e2e.rst | 6 +- specification/application_service_api.rst | 8 +- specification/client_server_api.rst | 124 ++++++------------ specification/intro.rst | 3 + specification/modules/account_data.rst | 8 +- specification/modules/guest_access.rst | 18 +-- specification/modules/push.rst | 10 +- specification/modules/receipts.rst | 4 +- specification/modules/tags.rst | 8 +- 41 files changed, 137 insertions(+), 178 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 6e3198ef..fb50498f 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -38,4 +38,4 @@ Specification changes in v0.1.0 (2015-06-01) ============================================ - First numbered release. - Restructure the format of Event information. Add more information. -- Restructure the format of the Client-Server HTTP APIs. \ No newline at end of file +- Restructure the format of the Client-Server HTTP APIs. diff --git a/api/client-server/account-data.yaml b/api/client-server/account-data.yaml index b634dddc..111099d5 100644 --- a/api/client-server/account-data.yaml +++ b/api/client-server/account-data.yaml @@ -6,7 +6,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 7e3f8bce..8162c4c9 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Account Administrative Contact API" + title: "Matrix Client-Server Account Administrative Contact API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/banning.yaml b/api/client-server/banning.yaml index e841050f..f4f4b15b 100644 --- a/api/client-server/banning.yaml +++ b/api/client-server/banning.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Banning API" + title: "Matrix Client-Server Room Banning API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 8e6e8d1a..34194952 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -1,11 +1,11 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Content Repository API" + title: "Matrix Client-Server Content Repository API" version: "1.0.0" host: localhost:8008 schemes: - https -basePath: /_matrix/media/v1 +basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% produces: - application/json - "*/*" diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 20c00f6c..60f9599d 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Creation API" + title: "Matrix Client-Server Room Creation API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 4966a920..7b3cc889 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Directory API" + title: "Matrix Client-Server Directory API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1/directory +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory consumes: - application/json produces: diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml index 0c2761b7..3350135f 100644 --- a/api/client-server/filter.yaml +++ b/api/client-server/filter.yaml @@ -1,11 +1,11 @@ swagger: '2.0' info: - title: "Matrix Client-Server v2 filter API" + title: "Matrix Client-Server filter API" version: "1.0.0" host: localhost:8008 schemes: - https -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/guest_events.yaml b/api/client-server/guest_events.yaml index 4d7a957d..85f5c6b7 100644 --- a/api/client-server/guest_events.yaml +++ b/api/client-server/guest_events.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Sync Guest API" + title: "Matrix Client-Server Sync Guest API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/inviting.yaml b/api/client-server/inviting.yaml index d9b0ad10..7bc703c7 100644 --- a/api/client-server/inviting.yaml +++ b/api/client-server/inviting.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Joining API" + title: "Matrix Client-Server Room Joining API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index b6d2df18..530fa1b6 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Inviting API" + title: "Matrix Client-Server Room Inviting API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: @@ -63,6 +63,6 @@ paths: schema: "$ref": "definitions/error.yaml" x-alias: - canonical-link: "post-matrix-client-api-v1-rooms-roomid-join" + canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join" aliases: - - /_matrix/client/api/v1/join/{roomId} + - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId} diff --git a/api/client-server/leaving.yaml b/api/client-server/leaving.yaml index e81d812b..36a375fe 100644 --- a/api/client-server/leaving.yaml +++ b/api/client-server/leaving.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Leaving API" + title: "Matrix Client-Server Room Leaving API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 23b1c3d0..c1c83093 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Creation API" + title: "Matrix Client-Server Room Creation API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index f2e3d044..2335dcb7 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Registration and Login API" + title: "Matrix Client-Server Registration and Login API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index d2bc0554..40c4c754 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Rooms API" + title: "Matrix Client-Server Rooms API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml index fe76e3bc..bdbf64b9 100644 --- a/api/client-server/old_sync.yaml +++ b/api/client-server/old_sync.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Sync API" + title: "Matrix Client-Server Sync API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index 6ac204dd..81272711 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Presence API" + title: "Matrix Client-Server Presence API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/profile.yaml b/api/client-server/profile.yaml index e19466bf..ccdccc25 100644 --- a/api/client-server/profile.yaml +++ b/api/client-server/profile.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Profile API" + title: "Matrix Client-Server Profile API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/push_notifier.yaml b/api/client-server/push_notifier.yaml index be3b5f74..420d4183 100644 --- a/api/client-server/push_notifier.yaml +++ b/api/client-server/push_notifier.yaml @@ -6,7 +6,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/push/v1 +basePath: /_matrix/push/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index ed6c4f91..6426618a 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Push API" + title: "Matrix Client-Server Push API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index 31e84f55..8ac50ac7 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Push Rules API" + title: "Matrix Client-Server Push Rules API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/receipts.yaml b/api/client-server/receipts.yaml index b60f72e6..d3e65e09 100644 --- a/api/client-server/receipts.yaml +++ b/api/client-server/receipts.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v2 Receipts API" + title: "Matrix Client-Server Receipts API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 7bb49f2c..df6cafe4 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v2 Registration API" + title: "Matrix Client-Server Registration API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/room_send.yaml b/api/client-server/room_send.yaml index 3ab1ac40..dad54353 100644 --- a/api/client-server/room_send.yaml +++ b/api/client-server/room_send.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 message event send API" + title: "Matrix Client-Server message event send API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index ec30fd34..21737e1c 100644 --- a/api/client-server/room_state.yaml +++ b/api/client-server/room_state.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 state event send API" + title: "Matrix Client-Server state event send API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index cc3aecc4..c426ffa2 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Rooms API" + title: "Matrix Client-Server Rooms API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 8a8c3f5a..66285f1d 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Search API" + title: "Matrix Client-Server Search API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: @@ -67,7 +67,7 @@ paths: title: Filter description: |- The filter to apply to search results. - This has the same format as v2 filter API. + This has the same format as filter API. required: ["search_term"] required: ["search_categories"] responses: diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 675eda5d..b9c20045 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -1,11 +1,11 @@ swagger: '2.0' info: - title: "Matrix Client-Server v2 sync API" + title: "Matrix Client-Server sync API" version: "1.0.0" host: localhost:8008 schemes: - https -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 91945dca..76201034 100644 --- a/api/client-server/tags.yaml +++ b/api/client-server/tags.yaml @@ -6,7 +6,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index e9c4d2f2..80065be9 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Room Membership API for third party identifiers" + title: "Matrix Client-Server Room Membership API for third party identifiers" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/typing.yaml b/api/client-server/typing.yaml index 737c6928..65e0634a 100644 --- a/api/client-server/typing.yaml +++ b/api/client-server/typing.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Typing API" + title: "Matrix Client-Server Typing API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/client-server/voip.yaml b/api/client-server/voip.yaml index 629f2c17..983cfe93 100644 --- a/api/client-server/voip.yaml +++ b/api/client-server/voip.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Voice over IP API" + title: "Matrix Client-Server Voice over IP API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: diff --git a/drafts/e2e.rst b/drafts/e2e.rst index 8b38ab93..e49958a8 100644 --- a/drafts/e2e.rst +++ b/drafts/e2e.rst @@ -115,7 +115,7 @@ The JSON object is signed using the process given by `Signing JSON`_. .. code:: http - POST /_matrix/client/v2_alpha/keys/upload/ HTTP/1.1 + POST /_matrix/client/%CLIENT_MAJOR_VERSION%/keys/upload/ HTTP/1.1 Content-Type: application/json { @@ -206,7 +206,7 @@ lies about the keys a user owns. } } } } } } -Clients use ``/_matrix/client/v2_alpha/keys/query`` on their own homeservers to +Clients use ``/_matrix/client/%CLIENT_MAJOR_VERSION%/keys/query`` on their own homeservers to query keys for any user they wish to contact. Homeservers will respond with the keys for their local users and forward requests for remote users to ``/_matrix/federation/v1/user/keys/query`` over federation to the remote @@ -263,7 +263,7 @@ time key once it has given that key to another user. } } } } -Clients use ``/_matrix/client/v2_alpha/keys/claim`` on their own homeservers to +Clients use ``/_matrix/client/%CLIENT_MAJOR_VERSION%/keys/claim`` on their own homeservers to claim keys for any user they wish to contact. Homeservers will respond with the keys for their local users and forward requests for remote users to ``/_matrix/federation/v1/user/keys/claim`` over federation to the remote diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 7717a64e..1f442748 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -153,10 +153,10 @@ application services MUST implement these APIs. These APIs are defined below. .. _create the user: `sect:asapi-permissions`_ -Client-Server v2 API Extensions +Client-Server API Extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Application services can utilise a more powerful version of the +Application services can use a more powerful version of the client-server API by identifying itself as an application service to the homeserver. @@ -281,7 +281,7 @@ an API is exposed. :: - GET /_matrix/app/v1/user?uri=$url_encoded_uri + GET /_matrix/app/%CLIENT_MAJOR_VERSION%/user?uri=$url_encoded_uri Returns 200 OK: { @@ -305,7 +305,7 @@ SHOULD be mapped in the same way as "user" URIs. :: - GET /_matrix/app/v1/alias?uri=$url_encoded_uri + GET /_matrix/app/%CLIENT_MAJOR_VERSION%/alias?uri=$url_encoded_uri Returns 200 OK: { diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 77831bef..8def2ae1 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -7,16 +7,6 @@ support both lightweight clients which store no state and lazy-load data from the server as required - as well as heavyweight clients which maintain a full local persistent copy of server state. -This mostly describes v1 of the Client-Server API as featured in the original September -2014 launch of Matrix, apart from user-interactive authentication where it is -encouraged to move to v2, therefore this is the version documented here. -Version 2 is currently in development (as of Jan-March 2015) as an incremental -but backwards-incompatible refinement of Version 1 and will be released -shortly. - -Documentation for the old `V1 authentication -<../attic/v1_registration_login.rst>`_ is still available separately. - .. contents:: Table of Contents .. sectnum:: @@ -93,41 +83,17 @@ Some requests have unique error codes: .. _sect:txn_ids: -The Client-Server API typically uses ``HTTP POST`` to submit requests. This -means these requests are not idempotent. The C-S API also allows ``HTTP PUT`` to -make requests idempotent. In order to use a ``PUT``, paths should be suffixed -with ``/{txnId}``. ``{txnId}`` is a unique client-generated transaction ID which -identifies the request, and is scoped to a given Client (identified by that -client's ``access_token``). Crucially, it **only** serves to identify new +The Client-Server API typically uses ``HTTP PUT`` to submit requests with a +client-generated transaction identifier. This means that these requests are +idempotent. The scope of a transaction identifier is a particular access token. +It **only** serves to identify new requests from retransmits. After the request has finished, the ``{txnId}`` value should be changed (how is not specified; a monotonically increasing -integer is recommended). It is preferable to use ``HTTP PUT`` to make sure -requests to send messages do not get sent more than once should clients need to -retransmit requests. - -Valid requests look like:: +integer is recommended). - POST /some/path/here?access_token=secret - { - "key": "This is a post." - } - - PUT /some/path/here/11?access_token=secret - { - "key": "This is a put with a txnId of 11." - } - -In contrast, these are invalid requests:: - - POST /some/path/here/11?access_token=secret - { - "key": "This is a post, but it has a txnId." - } - - PUT /some/path/here?access_token=secret - { - "key": "This is a put but it is missing a txnId." - } +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. Client Authentication --------------------- @@ -135,7 +101,7 @@ Most API endpoints require the user to identify themselves by presenting previously obtained credentials in the form of an ``access_token`` query parameter. -In API version 2, when credentials are missing or invalid, the HTTP call will +When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or ``M_UNKNOWN_TOKEN`` respectively. @@ -144,8 +110,6 @@ User-Interactive Authentication API .. _sect:auth-api: -This section refers to API Version 2. - Some API endpoints such as ``login`` or ``register`` require authentication that interacts with the user. The homeserver may provide many different ways of authenticating, such as user/password auth, login via a social network (OAuth2), @@ -450,9 +414,9 @@ Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login type, it can direct the user to a web browser with the URL of a fallback page which will allow the user to complete that login step out-of-band in their web browser. The URL it -should open is the homeserver base URL plus prefix, plus:: +should open is:: - /auth//fallback/web?session= + /_matrix/client/%CLIENT_MAJOR_VERSION%/auth//fallback/web?session= Where ``stage type`` is the type name of the stage it is attempting and ``session id`` is the ID of the session given by the homeserver. @@ -463,15 +427,10 @@ the authentication has been completed. API calls using the User-Interactive Authentication mechanism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section refers to API Version 2. These API calls currently use the prefix -``/_matrix/client/v2_alpha``. - .. _User-Interactive Authentication: `sect:auth-api`_ {{registration_http_api}} -Old V1 API docs: |register|_ - {{login_http_api}} Login Fallback @@ -490,7 +449,7 @@ Changing Password +++++++++++++++++ Request:: - POST $V2PREFIX/account/password + POST /_matrix/client/%CLIENT_MAJOR_VERSION%/account/password This API endpoint uses the User-Interactive Authentication API. An access token should be submitted to this endpoint if the client has an active session. The @@ -622,15 +581,21 @@ point in time:: [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9] -Clients can add to the stream by POSTing message or state events, and can read -from the stream via the |initialSync|_, |/rooms//initialSync|_, `Event -Stream`_ and |/rooms//messages|_ APIs. +Clients can add to the stream by PUTing message or state events, and can read +from the stream via the +|initialSync|_, +|events|_, +|/rooms//initialSync|_, and +|/rooms//messages|_ +APIs. For reading events, the intended flow of operation is to call -$PREFIX/initialSync, which returns all of the state and the last N events in the +/_matrix/client/%CLIENT_MAJOR_VERSION%/initialSync, which returns all of the +state and the last N events in the event stream for each room, including ``start`` and ``end`` values describing the pagination of each room's event stream. For instance, -$PREFIX/initialSync?limit=5 might return the events for a room in the +/_matrix/client/%CLIENT_MAJOR_VERSION%/initialSync?limit=5 might return the +events for a room in the rooms[0].messages.chunk[] array, with tokens describing the start and end of the range in rooms[0].messages.start as '1-2-3' and rooms[0].messages.end as 'a-b-c'. @@ -643,7 +608,8 @@ You can visualise the range of events being returned as:: start: '1-2-3' end: 'a-b-c' Now, to receive future events in real-time on the event stream, you simply GET -$PREFIX/events with a ``from`` parameter of 'a-b-c': in other words passing in the +/_matrix/client/%CLIENT_MAJOR_VERSION%/events with a ``from`` parameter of +'a-b-c': in other words passing in the ``end`` token returned by initial sync. The request blocks until new events are available or until your specified timeout elapses, and then returns a new paginatable chunk of events alongside new start and end parameters:: @@ -655,10 +621,11 @@ new paginatable chunk of events alongside new start and end parameters:: start: 'a-b-c' To resume polling the events stream, you pass in the new ``end`` token as the -``from`` parameter of $PREFIX/events and poll again. +``from`` parameter of /_matrix/client/%CLIENT_MAJOR_VERSION%/events and poll again. Similarly, to paginate events backwards in order to lazy-load in previous -history from the room, you simply GET $PREFIX/rooms//messages +history from the room, you simply +GET /_matrix/client/%CLIENT_MAJOR_VERSION%/rooms//messages specifying the ``from`` token to paginate backwards from and a limit of the number of messages to retrieve. For instance, calling this API with a ``from`` parameter of '1-2-3' and a limit of 5 would return:: @@ -1023,44 +990,33 @@ have to wait in milliseconds before they can try again. .. Links through the external API docs are below .. ============================================= -.. |createRoom| replace:: ``/createRoom`` -.. _createRoom: /docs/api/client-server/#!/-rooms/create_room - .. |initialSync| replace:: ``/initialSync`` -.. _initialSync: /docs/api/client-server/#!/-events/initial_sync +.. _initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync -.. |/rooms//initialSync| replace:: ``/rooms//initialSync`` -.. _/rooms//initialSync: /docs/api/client-server/#!/-rooms/get_room_sync_data - -.. |login| replace:: ``/login`` -.. _login: /docs/api/client-server/#!/-login +.. |events| replace:: ``/events`` +.. _events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events -.. |register| replace:: ``/register`` -.. _register: /docs/api/client-server/#!/-registration +.. |/rooms//initialSync| replace:: ``/rooms//initialSync`` +.. _/rooms//initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync .. |/rooms//messages| replace:: ``/rooms//messages`` -.. _/rooms//messages: /docs/api/client-server/#!/-rooms/get_messages +.. _/rooms//messages: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages .. |/rooms//members| replace:: ``/rooms//members`` -.. _/rooms//members: /docs/api/client-server/#!/-rooms/get_members +.. _/rooms//members: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-members .. |/rooms//state| replace:: ``/rooms//state`` -.. _/rooms//state: /docs/api/client-server/#!/-rooms/get_state_events +.. _/rooms//state: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state .. |/rooms//invite| replace:: ``/rooms//invite`` -.. _/rooms//invite: /docs/api/client-server/#!/-rooms/invite +.. _/rooms//invite: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite .. |/rooms//join| replace:: ``/rooms//join`` -.. _/rooms//join: /docs/api/client-server/#!/-rooms/join_room +.. _/rooms//join: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join .. |/rooms//leave| replace:: ``/rooms//leave`` -.. _/rooms//leave: /docs/api/client-server/#!/-rooms/leave +.. _/rooms//leave: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-leave .. |/rooms//ban| replace:: ``/rooms//ban`` -.. _/rooms//ban: /docs/api/client-server/#!/-rooms/ban - -.. |/join/| replace:: ``/join/`` -.. _/join/: /docs/api/client-server/#!/-rooms/join - -.. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream +.. _/rooms//ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban diff --git a/specification/intro.rst b/specification/intro.rst index ced721fa..cd28b9f7 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -15,6 +15,9 @@ The following APIs are documented in this specification: There are also some `appendices `_. +Before we formally started releasing the specification, the last working copy +we had can be found `here `_. + .. contents:: Table of Contents .. sectnum:: diff --git a/specification/modules/account_data.rst b/specification/modules/account_data.rst index f3fc72b6..e7c650ac 100644 --- a/specification/modules/account_data.rst +++ b/specification/modules/account_data.rst @@ -14,11 +14,11 @@ Events ------ The client recieves the account data as events in the ``account_data`` sections -of a v2 /sync. +of a ``/sync``. -These events can also be received in a v1 /events response or in the -``account_data`` section of a room in v1 /initialSync. ``m.tag`` -events appearing in v1 /events will have a ``room_id`` with the room +These events can also be received in a ``/events`` response or in the +``account_data`` section of a room in ``/initialSync``. ``m.tag`` +events appearing in ``/events`` will have a ``room_id`` with the room the tags are for. Client Behaviour diff --git a/specification/modules/guest_access.rst b/specification/modules/guest_access.rst index 1f393981..cd43524b 100644 --- a/specification/modules/guest_access.rst +++ b/specification/modules/guest_access.rst @@ -9,7 +9,7 @@ the room. This module specifies how these clients should interact with servers in order to participate in rooms as guests. Guest users retrieve access tokens from a homeserver using the ordinary -`register endpoint <#post-matrix-client-api-v2-alpha-register>`_, specifying +`register endpoint <#post-matrix-client-%CLIENT_MAJOR_VERSION%-register>`_, specifying the ``kind`` parameter as ``guest``. They may then interact with the client-server API as any other user would, but will only have access to a subset of the API as described the Client behaviour subsection below. @@ -29,13 +29,13 @@ Client behaviour The following API endpoints are allowed to be accessed by guest accounts for retrieving events: -* `GET /rooms/:room_id/state <#get-matrix-client-api-v1-rooms-roomid-state>`_ -* `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-api-v1-rooms-roomid-state-eventtype-statekey>`_ -* `GET /rooms/:room_id/messages <#get-matrix-client-api-v1-rooms-roomid-messages>`_ -* `GET /rooms/:room_id/initialSync <#get-matrix-client-api-v1-rooms-roomid-initialsync>`_ +* `GET /rooms/:room_id/state <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state>`_ +* `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype-statekey>`_ +* `GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_ +* `GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_ There is also a special version of the -`GET /events <#get-matrix-client-api-v1-events>`_ endpoint: +`GET /events <#get-matrix-client-%CLIENT_MAJOR_VERSION%-events>`_ endpoint: {{guest_events_http_api}} @@ -47,15 +47,15 @@ receive events for them. The following API endpoints are allowed to be accessed by guest accounts for sending events: -* `POST /rooms/:room_id/join <#post-matrix-client-api-v1-rooms-roomid-join>`_ -* `PUT /rooms/:room_id/send/m.room.message/:txn_id <#put-matrix-client-api-v1-rooms-roomid-send-eventtype-txnid>`_ +* `POST /rooms/:room_id/join <#post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join>`_ +* `PUT /rooms/:room_id/send/m.room.message/:txn_id <#put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-send-eventtype-txnid>`_ Guest clients *do* need to join rooms in order to send events to them. The following API endpoints are allowed to be accessed by guest accounts for their own account maintenance: -* `PUT /profile/:user_id/displayname <#put-matrix-client-api-v1-profile-userid-displayname>`_ +* `PUT /profile/:user_id/displayname <#put-matrix-client-%CLIENT_MAJOR_VERSION%-profile-userid-displayname>`_ Server behaviour ---------------- diff --git a/specification/modules/push.rst b/specification/modules/push.rst index de45bfe6..2834688c 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -355,14 +355,14 @@ Examples To create a rule that suppresses notifications for the room with ID ``!dj234r78wl45Gh4D:matrix.org``:: - curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \ + curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \ '{ "actions" : ["dont_notify"] }' To suppress notifications for the user ``@spambot:matrix.org``:: - curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \ + curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \ '{ "actions" : ["dont_notify"] }' @@ -370,7 +370,7 @@ To suppress notifications for the user ``@spambot:matrix.org``:: To always notify for messages that contain the work 'cake' and set a specific sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``):: - curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \ + curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \ '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] @@ -379,7 +379,7 @@ sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``):: To add a rule suppressing notifications for messages starting with 'cake' but ending with 'lie', superseding the previous rule:: - curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \ + curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \ '{ "pattern": "cake*lie", "actions" : ["notify"] @@ -389,7 +389,7 @@ To add a custom sound for notifications messages containing the word 'beer' in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules):: - curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \ + curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \ '{ "conditions": [ {"kind": "event_match", "key": "content.body", "pattern": "beer" }, diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index 702a7275..70135801 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -24,8 +24,8 @@ single ``event_id``. Client behaviour ---------------- -In v1 ``/initialSync``, receipts are listed in a separate top level ``receipts`` -key. In v2 ``/sync``, receipts are contained in the ``ephemeral`` block for a +In ``/initialSync``, receipts are listed in a separate top level ``receipts`` +key. In ``/sync``, receipts are contained in the ``ephemeral`` block for a room. New receipts that come down the event streams are deltas which update existing mappings. Clients should replace older receipt acknowledgements based on ``user_id`` and ``receipt_type`` pairs. For example:: diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index f8c28c55..4bed9657 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -11,11 +11,11 @@ Events ------ The tags on a room are received as single ``m.tag`` event in the -``account_data`` section of a room in a v2 /sync. +``account_data`` section of a room in a ``/sync``. -The ``m.tag`` can also be received in a v1 /events response or in the -``account_data`` section of a room in v1 /initialSync. ``m.tag`` -events appearing in v1 /events will have a ``room_id`` with the room +The ``m.tag`` can also be received in a ``/events`` response or in the +``account_data`` section of a room in ``/initialSync``. ``m.tag`` +events appearing in ``/events`` will have a ``room_id`` with the room the tags are for. Each tag has an associated JSON object with information about the tag, e.g how