Replace version numbers with release numbers

pull/977/head
Daniel Wagner-Hall 9 years ago
parent 8c874176d2
commit 873b0dcecf

@ -6,7 +6,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Account Administrative Contact API" title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Banning API" title: "Matrix Client-Server Room Banning API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,11 +1,11 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Content Repository API" title: "Matrix Client-Server Content Repository API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
basePath: /_matrix/media/v1 basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
produces: produces:
- application/json - application/json
- "*/*" - "*/*"

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Creation API" title: "Matrix Client-Server Room Creation API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Directory API" title: "Matrix Client-Server Directory API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1/directory basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,11 +1,11 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v2 filter API" title: "Matrix Client-Server filter API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Sync Guest API" title: "Matrix Client-Server Sync Guest API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Joining API" title: "Matrix Client-Server Room Joining API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Inviting API" title: "Matrix Client-Server Room Inviting API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:
@ -63,6 +63,6 @@ paths:
schema: schema:
"$ref": "definitions/error.yaml" "$ref": "definitions/error.yaml"
x-alias: x-alias:
canonical-link: "post-matrix-client-api-v1-rooms-roomid-join" canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
aliases: aliases:
- /_matrix/client/api/v1/join/{roomId} - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Leaving API" title: "Matrix Client-Server Room Leaving API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Room Creation API" title: "Matrix Client-Server Room Creation API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Registration and Login API" title: "Matrix Client-Server Registration and Login API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Rooms API" title: "Matrix Client-Server Rooms API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Sync API" title: "Matrix Client-Server Sync API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Presence API" title: "Matrix Client-Server Presence API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Profile API" title: "Matrix Client-Server Profile API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -6,7 +6,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/push/v1 basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Push API" title: "Matrix Client-Server Push API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Push Rules API" title: "Matrix Client-Server Push Rules API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v2 Receipts API" title: "Matrix Client-Server Receipts API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v2 Registration API" title: "Matrix Client-Server Registration API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 message event send API" title: "Matrix Client-Server message event send API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 state event send API" title: "Matrix Client-Server state event send API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Rooms API" title: "Matrix Client-Server Rooms API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Search API" title: "Matrix Client-Server Search API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:
@ -67,7 +67,7 @@ paths:
title: Filter title: Filter
description: |- description: |-
The filter to apply to search results. 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_term"]
required: ["search_categories"] required: ["search_categories"]
responses: responses:

@ -1,11 +1,11 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v2 sync API" title: "Matrix Client-Server sync API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -6,7 +6,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/v2_alpha basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: 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" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Typing API" title: "Matrix Client-Server Typing API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -1,12 +1,12 @@
swagger: '2.0' swagger: '2.0'
info: info:
title: "Matrix Client-Server v1 Voice over IP API" title: "Matrix Client-Server Voice over IP API"
version: "1.0.0" version: "1.0.0"
host: localhost:8008 host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/client/api/v1 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes: consumes:
- application/json - application/json
produces: produces:

@ -115,7 +115,7 @@ The JSON object is signed using the process given by `Signing JSON`_.
.. code:: http .. code:: http
POST /_matrix/client/v2_alpha/keys/upload/<device_id> HTTP/1.1 POST /_matrix/client/%CLIENT_MAJOR_VERSION%/keys/upload/<device_id> HTTP/1.1
Content-Type: application/json 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 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 keys for their local users and forward requests for remote users to
``/_matrix/federation/v1/user/keys/query`` over federation to the remote ``/_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 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 keys for their local users and forward requests for remote users to
``/_matrix/federation/v1/user/keys/claim`` over federation to the remote ``/_matrix/federation/v1/user/keys/claim`` over federation to the remote

@ -153,10 +153,10 @@ application services MUST implement these APIs. These APIs are defined below.
.. _create the user: `sect:asapi-permissions`_ .. _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 client-server API by identifying itself as an application service to the
homeserver. 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: 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: Returns 200 OK:
{ {

@ -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 the server as required - as well as heavyweight clients which maintain a full
local persistent copy of server state. 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 .. contents:: Table of Contents
.. sectnum:: .. sectnum::
@ -93,41 +83,17 @@ Some requests have unique error codes:
.. _sect:txn_ids: .. _sect:txn_ids:
The Client-Server API typically uses ``HTTP POST`` to submit requests. This The Client-Server API typically uses ``HTTP PUT`` to submit requests with a
means these requests are not idempotent. The C-S API also allows ``HTTP PUT`` to client-generated transaction identifier. This means that these requests are
make requests idempotent. In order to use a ``PUT``, paths should be suffixed idempotent. The scope of a transaction identifier is a particular access token.
with ``/{txnId}``. ``{txnId}`` is a unique client-generated transaction ID which It **only** serves to identify new
identifies the request, and is scoped to a given Client (identified by that
client's ``access_token``). Crucially, it **only** serves to identify new
requests from retransmits. After the request has finished, the ``{txnId}`` requests from retransmits. After the request has finished, the ``{txnId}``
value should be changed (how is not specified; a monotonically increasing value should be changed (how is not specified; a monotonically increasing
integer is recommended). It is preferable to use ``HTTP PUT`` to make sure integer is recommended).
requests to send messages do not get sent more than once should clients need to
retransmit requests.
Valid requests look like::
POST /some/path/here?access_token=secret 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
"key": "This is a post." recommended.
}
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."
}
Client Authentication 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 previously obtained credentials in the form of an ``access_token`` query
parameter. 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 return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
``M_UNKNOWN_TOKEN`` respectively. ``M_UNKNOWN_TOKEN`` respectively.
@ -144,8 +110,6 @@ User-Interactive Authentication API
.. _sect:auth-api: .. _sect:auth-api:
This section refers to API Version 2.
Some API endpoints such as ``login`` or ``register`` require authentication that Some API endpoints such as ``login`` or ``register`` require authentication that
interacts with the user. The homeserver may provide many different ways of interacts with the user. The homeserver may provide many different ways of
authenticating, such as user/password auth, login via a social network (OAuth2), 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 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 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 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/<stage type>/fallback/web?session=<session ID> /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<stage type>/fallback/web?session=<session ID>
Where ``stage type`` is the type name of the stage it is attempting and 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. ``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 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`_ .. _User-Interactive Authentication: `sect:auth-api`_
{{registration_http_api}} {{registration_http_api}}
Old V1 API docs: |register|_
{{login_http_api}} {{login_http_api}}
Login Fallback Login Fallback
@ -490,7 +449,7 @@ Changing Password
+++++++++++++++++ +++++++++++++++++
Request:: 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 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 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] [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 Clients can add to the stream by PUTing message or state events, and can read
from the stream via the |initialSync|_, |/rooms/<room_id>/initialSync|_, `Event from the stream via the
Stream`_ and |/rooms/<room_id>/messages|_ APIs. |initialSync|_,
|events|_,
|/rooms/<room_id>/initialSync|_, and
|/rooms/<room_id>/messages|_
APIs.
For reading events, the intended flow of operation is to call 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 event stream for each room, including ``start`` and ``end`` values describing the
pagination of each room's event stream. For instance, 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 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 range in rooms[0].messages.start as '1-2-3' and rooms[0].messages.end as
'a-b-c'. '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' start: '1-2-3' end: 'a-b-c'
Now, to receive future events in real-time on the event stream, you simply GET 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 ``end`` token returned by initial sync. The request blocks until new events are
available or until your specified timeout elapses, and then returns a available or until your specified timeout elapses, and then returns a
new paginatable chunk of events alongside new start and end parameters:: 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' start: 'a-b-c'
To resume polling the events stream, you pass in the new ``end`` token as the 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 Similarly, to paginate events backwards in order to lazy-load in previous
history from the room, you simply GET $PREFIX/rooms/<room_id>/messages history from the room, you simply
GET /_matrix/client/%CLIENT_MAJOR_VERSION%/rooms/<room_id>/messages
specifying the ``from`` token to paginate backwards from and a limit of the number 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 messages to retrieve. For instance, calling this API with a ``from`` parameter
of '1-2-3' and a limit of 5 would return:: 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 .. Links through the external API docs are below
.. ============================================= .. =============================================
.. |createRoom| replace:: ``/createRoom``
.. _createRoom: /docs/api/client-server/#!/-rooms/create_room
.. |initialSync| replace:: ``/initialSync`` .. |initialSync| replace:: ``/initialSync``
.. _initialSync: /docs/api/client-server/#!/-events/initial_sync .. _initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync
.. |/rooms/<room_id>/initialSync| replace:: ``/rooms/<room_id>/initialSync`` .. |events| replace:: ``/events``
.. _/rooms/<room_id>/initialSync: /docs/api/client-server/#!/-rooms/get_room_sync_data .. _events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events
.. |login| replace:: ``/login``
.. _login: /docs/api/client-server/#!/-login
.. |register| replace:: ``/register`` .. |/rooms/<room_id>/initialSync| replace:: ``/rooms/<room_id>/initialSync``
.. _register: /docs/api/client-server/#!/-registration .. _/rooms/<room_id>/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync
.. |/rooms/<room_id>/messages| replace:: ``/rooms/<room_id>/messages`` .. |/rooms/<room_id>/messages| replace:: ``/rooms/<room_id>/messages``
.. _/rooms/<room_id>/messages: /docs/api/client-server/#!/-rooms/get_messages .. _/rooms/<room_id>/messages: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages
.. |/rooms/<room_id>/members| replace:: ``/rooms/<room_id>/members`` .. |/rooms/<room_id>/members| replace:: ``/rooms/<room_id>/members``
.. _/rooms/<room_id>/members: /docs/api/client-server/#!/-rooms/get_members .. _/rooms/<room_id>/members: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-members
.. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state`` .. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
.. _/rooms/<room_id>/state: /docs/api/client-server/#!/-rooms/get_state_events .. _/rooms/<room_id>/state: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state
.. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite`` .. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
.. _/rooms/<room_id>/invite: /docs/api/client-server/#!/-rooms/invite .. _/rooms/<room_id>/invite: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite
.. |/rooms/<room_id>/join| replace:: ``/rooms/<room_id>/join`` .. |/rooms/<room_id>/join| replace:: ``/rooms/<room_id>/join``
.. _/rooms/<room_id>/join: /docs/api/client-server/#!/-rooms/join_room .. _/rooms/<room_id>/join: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join
.. |/rooms/<room_id>/leave| replace:: ``/rooms/<room_id>/leave`` .. |/rooms/<room_id>/leave| replace:: ``/rooms/<room_id>/leave``
.. _/rooms/<room_id>/leave: /docs/api/client-server/#!/-rooms/leave .. _/rooms/<room_id>/leave: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-leave
.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban`` .. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
.. _/rooms/<room_id>/ban: /docs/api/client-server/#!/-rooms/ban .. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
.. |/join/<room_alias_or_id>| replace:: ``/join/<room_alias_or_id>``
.. _/join/<room_alias_or_id>: /docs/api/client-server/#!/-rooms/join
.. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream

@ -15,6 +15,9 @@ The following APIs are documented in this specification:
There are also some `appendices <appendices.html>`_. There are also some `appendices <appendices.html>`_.
Before we formally started releasing the specification, the last working copy
we had can be found `here <https://matrix.org/docs/spec/legacy/>`_.
.. contents:: Table of Contents .. contents:: Table of Contents
.. sectnum:: .. sectnum::

@ -14,11 +14,11 @@ Events
------ ------
The client recieves the account data as events in the ``account_data`` sections 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 These events can also be received in a ``/events`` response or in the
``account_data`` section of a room in v1 /initialSync. ``m.tag`` ``account_data`` section of a room in ``/initialSync``. ``m.tag``
events appearing in v1 /events will have a ``room_id`` with the room events appearing in ``/events`` will have a ``room_id`` with the room
the tags are for. the tags are for.
Client Behaviour Client Behaviour

@ -9,7 +9,7 @@ the room. This module specifies how these clients should interact with servers
in order to participate in rooms as guests. in order to participate in rooms as guests.
Guest users retrieve access tokens from a homeserver using the ordinary 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 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 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. 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 The following API endpoints are allowed to be accessed by guest accounts for
retrieving events: retrieving events:
* `GET /rooms/:room_id/state <#get-matrix-client-api-v1-rooms-roomid-state>`_ * `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-api-v1-rooms-roomid-state-eventtype-statekey>`_ * `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-api-v1-rooms-roomid-messages>`_ * `GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_
* `GET /rooms/:room_id/initialSync <#get-matrix-client-api-v1-rooms-roomid-initialsync>`_ * `GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_
There is also a special version of the 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}} {{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 The following API endpoints are allowed to be accessed by guest accounts for
sending events: sending events:
* `POST /rooms/:room_id/join <#post-matrix-client-api-v1-rooms-roomid-join>`_ * `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-api-v1-rooms-roomid-send-eventtype-txnid>`_ * `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. 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 The following API endpoints are allowed to be accessed by guest accounts for
their own account maintenance: 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 Server behaviour
---------------- ----------------

@ -355,14 +355,14 @@ Examples
To create a rule that suppresses notifications for the room with ID To create a rule that suppresses notifications for the room with ID
``!dj234r78wl45Gh4D:matrix.org``:: ``!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"] "actions" : ["dont_notify"]
}' }'
To suppress notifications for the user ``@spambot:matrix.org``:: 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"] "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 To always notify for messages that contain the work 'cake' and set a specific
sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``):: 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", "pattern": "cake",
"actions" : ["notify", {"set_sound":"cakealarm.wav"}] "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 To add a rule suppressing notifications for messages starting with 'cake' but
ending with 'lie', superseding the previous rule:: 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", "pattern": "cake*lie",
"actions" : ["notify"] "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, any rooms with 10 members or fewer (with greater importance than the room,
sender and content rules):: 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": [ "conditions": [
{"kind": "event_match", "key": "content.body", "pattern": "beer" }, {"kind": "event_match", "key": "content.body", "pattern": "beer" },

@ -24,8 +24,8 @@ single ``event_id``.
Client behaviour Client behaviour
---------------- ----------------
In v1 ``/initialSync``, receipts are listed in a separate top level ``receipts`` In ``/initialSync``, receipts are listed in a separate top level ``receipts``
key. In v2 ``/sync``, receipts are contained in the ``ephemeral`` block for a 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 room. New receipts that come down the event streams are deltas which update
existing mappings. Clients should replace older receipt acknowledgements based existing mappings. Clients should replace older receipt acknowledgements based
on ``user_id`` and ``receipt_type`` pairs. For example:: on ``user_id`` and ``receipt_type`` pairs. For example::

@ -11,11 +11,11 @@ Events
------ ------
The tags on a room are received as single ``m.tag`` event in the 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 The ``m.tag`` can also be received in a ``/events`` response or in the
``account_data`` section of a room in v1 /initialSync. ``m.tag`` ``account_data`` section of a room in ``/initialSync``. ``m.tag``
events appearing in v1 /events will have a ``room_id`` with the room events appearing in ``/events`` will have a ``room_id`` with the room
the tags are for. the tags are for.
Each tag has an associated JSON object with information about the tag, e.g how Each tag has an associated JSON object with information about the tag, e.g how

Loading…
Cancel
Save