From d7d7f53884fe7812fe1aa98f03191c0a33deb844 Mon Sep 17 00:00:00 2001 From: Oddvar Lovaas Date: Wed, 21 Sep 2016 16:03:34 +0100 Subject: [PATCH] Remove duplicates, add redirect --- .../guides/2015-08-10-client-server.rst | 652 ------------------ .../howtos/2014-06-09-client-server.md | 11 + .../client-server-migrating-from-v1.rst | 108 --- supporting-docs/howtos/client-server.rst | 387 ----------- .../projects/2015-04-02-vector-ios.md | 11 - 5 files changed, 11 insertions(+), 1158 deletions(-) delete mode 100644 supporting-docs/guides/2015-08-10-client-server.rst create mode 100644 supporting-docs/howtos/2014-06-09-client-server.md delete mode 100644 supporting-docs/howtos/client-server-migrating-from-v1.rst delete mode 100644 supporting-docs/howtos/client-server.rst delete mode 100644 supporting-docs/projects/2015-04-02-vector-ios.md diff --git a/supporting-docs/guides/2015-08-10-client-server.rst b/supporting-docs/guides/2015-08-10-client-server.rst deleted file mode 100644 index fe6b464a..00000000 --- a/supporting-docs/guides/2015-08-10-client-server.rst +++ /dev/null @@ -1,652 +0,0 @@ ---- -layout: post -title: Client-Server API -categories: guides ---- -| - -.. figure:: http://matrix.org/matrix.png - :width: 305px - :height: 130px - :alt: [matrix] - :align: center - - -How to use the client-server API -================================ - -.. NOTE:: - The git version of this document is {% project_version %} - -This guide focuses on how the client-server APIs *provided by the reference -homeserver* can be used. Since this is specific to a homeserver -implementation, there may be variations in relation to registering/logging in -which are not covered in extensive detail in this guide. - -If you haven't already, get a homeserver up and running on -``http://localhost:8008``. - - -Accounts -======== -Before you can send and receive messages, you must **register** for an account. -If you already have an account, you must **login** into it. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/register_login - -Registration ------------- -The aim of registration is to get a user ID and access token which you will need -when accessing other APIs:: - - curl -XPOST -d '{"user":"example", "password":"wordpass", "type":"m.login.password"}' "http://localhost:8008/_matrix/client/api/v1/register" - - { - "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc", - "home_server": "localhost", - "user_id": "@example:localhost" - } - -NB: If a ``user`` is not specified, one will be randomly generated for you. -If you do not specify a ``password``, you will be unable to login to the account -if you forget the ``access_token``. - -Implementation note: The matrix specification does not enforce how users -register with a server. It just specifies the URL path and absolute minimum -keys. The reference homeserver uses a username/password to authenticate user, -but other homeservers may use different methods. This is why you need to -specify the ``type`` of method. - -Login ------ -The aim when logging in is to get an access token for your existing user ID:: - - curl -XGET "http://localhost:8008/_matrix/client/api/v1/login" - - { - "flows": [ - { - "type": "m.login.password" - } - ] - } - - curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "http://localhost:8008/_matrix/client/api/v1/login" - - { - "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd", - "home_server": "localhost", - "user_id": "@example:localhost" - } - -Implementation note: Different homeservers may implement different methods for -logging in to an existing account. In order to check that you know how to login -to this homeserver, you must perform a ``GET`` first and make sure you -recognise the login type. If you do not know how to login, you can -``GET /login/fallback`` which will return a basic webpage which you can use to -login. The reference homeserver implementation support username/password login, -but other homeservers may support different login methods (e.g. OAuth2). - - -Communicating -============= - -In order to communicate with another user, you must **create a room** with that -user and **send a message** to that room. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/create_room_send_msg - -Creating a room ---------------- -If you want to send a message to someone, you have to be in a room with them. To -create a room:: - - curl -XPOST -d '{"room_alias_name":"tutorial"}' "http://localhost:8008/_matrix/client/api/v1/createRoom?access_token=YOUR_ACCESS_TOKEN" - - { - "room_alias": "#tutorial:localhost", - "room_id": "!CvcvRuDYDzTOzfKKgh:localhost" - } - -The "room alias" is a human-readable string which can be shared with other users -so they can join a room, rather than the room ID which is a randomly generated -string. You can have multiple room aliases per room. - -.. TODO(kegan) - How to add/remove aliases from an existing room. - - -Sending messages ----------------- -You can now send messages to this room:: - - curl -XPOST -d '{"msgtype":"m.text", "body":"hello"}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/send/m.room.message?access_token=YOUR_ACCESS_TOKEN" - - { - "event_id": "YUwRidLecu" - } - -The event ID returned is a unique ID which identifies this message. - -NB: There are no limitations to the types of messages which can be exchanged. -The only requirement is that ``"msgtype"`` is specified. The Matrix -specification outlines the following standard types: ``m.text``, ``m.image``, -``m.audio``, ``m.video``, ``m.location``, ``m.emote``. See the specification for -more information on these types. - -Users and rooms -=============== - -Each room can be configured to allow or disallow certain rules. In particular, -these rules may specify if you require an **invitation** from someone already in -the room in order to **join the room**. In addition, you may also be able to -join a room **via a room alias** if one was set up. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/room_memberships - -Inviting a user to a room -------------------------- -You can directly invite a user to a room like so:: - - curl -XPOST -d '{"user_id":"@myfriend:localhost"}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/invite?access_token=YOUR_ACCESS_TOKEN" - -This informs ``@myfriend:localhost`` of the room ID -``!CvcvRuDYDzTOzfKKgh:localhost`` and allows them to join the room. - -Joining a room via an invite ----------------------------- -If you receive an invite, you can join the room:: - - curl -XPOST -d '{}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/join?access_token=YOUR_ACCESS_TOKEN" - -NB: Only the person invited (``@myfriend:localhost``) can change the membership -state to ``"join"``. Repeatedly joining a room does nothing. - -Joining a room via an alias ---------------------------- -Alternatively, if you know the room alias for this room and the room config -allows it, you can directly join a room via the alias:: - - curl -XPOST -d '{}' "http://localhost:8008/_matrix/client/api/v1/join/%23tutorial%3Alocalhost?access_token=YOUR_ACCESS_TOKEN" - - { - "room_id": "!CvcvRuDYDzTOzfKKgh:localhost" - } - -You will need to use the room ID when sending messages, not the room alias. - -NB: If the room is configured to be an invite-only room, you will still require -an invite in order to join the room even though you know the room alias. As a -result, it is more common to see a room alias in relation to a public room, -which do not require invitations. - -Getting events -============== -An event is some interesting piece of data that a client may be interested in. -It can be a message in a room, a room invite, etc. There are many different ways -of getting events, depending on what the client already knows. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/event_stream - -Getting all state ------------------ -If the client doesn't know any information on the rooms the user is -invited/joined on, they can get all the user's state for all rooms:: - - curl -XGET "http://localhost:8008/_matrix/client/api/v1/initialSync?access_token=YOUR_ACCESS_TOKEN" - - { - "end": "s39_18_0", - "presence": [ - { - "content": { - "last_active_ago": 1061436, - "user_id": "@example:localhost" - }, - "type": "m.presence" - } - ], - "rooms": [ - { - "membership": "join", - "messages": { - "chunk": [ - { - "content": { - "@example:localhost": 10, - "default": 0 - }, - "event_id": "wAumPSTsWF", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.power_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "join_rule": "public" - }, - "event_id": "jrLVqKHKiI", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.join_rules", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 10 - }, - "event_id": "WpmTgsNWUZ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.add_state_level", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 0 - }, - "event_id": "qUMBJyKsTQ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.send_event_level", - "user_id": "@example:localhost" - }, - { - "content": { - "ban_level": 5, - "kick_level": 5 - }, - "event_id": "YAaDmKvoUW", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.ops_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "RJbPMtCutf", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409665586730, - "type": "m.room.member", - "user_id": "@example:localhost" - }, - { - "content": { - "body": "hello", - "hsob_ts": 1409665660439, - "msgtype": "m.text" - }, - "event_id": "YUwRidLecu", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "ts": 1409665660439, - "type": "m.room.message", - "user_id": "@example:localhost" - }, - { - "content": { - "membership": "invite" - }, - "event_id": "YjNuBKnPsb", - "membership": "invite", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@myfriend:localhost", - "ts": 1409666426819, - "type": "m.room.member", - "user_id": "@example:localhost" - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join", - "prev": "join" - }, - "event_id": "KWwdDjNZnm", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409666551582, - "type": "m.room.member", - "user_id": "@example:localhost" - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "JFLVteSvQc", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409666587265, - "type": "m.room.member", - "user_id": "@example:localhost" - } - ], - "end": "s39_18_0", - "start": "t1-11_18_0" - }, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state": [ - { - "content": { - "creator": "@example:localhost" - }, - "event_id": "dMUoqVTZca", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.create", - "user_id": "@example:localhost" - }, - { - "content": { - "@example:localhost": 10, - "default": 0 - }, - "event_id": "wAumPSTsWF", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.power_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "join_rule": "public" - }, - "event_id": "jrLVqKHKiI", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.join_rules", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 10 - }, - "event_id": "WpmTgsNWUZ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.add_state_level", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 0 - }, - "event_id": "qUMBJyKsTQ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.send_event_level", - "user_id": "@example:localhost" - }, - { - "content": { - "ban_level": 5, - "kick_level": 5 - }, - "event_id": "YAaDmKvoUW", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.ops_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "membership": "invite" - }, - "event_id": "YjNuBKnPsb", - "membership": "invite", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@myfriend:localhost", - "ts": 1409666426819, - "type": "m.room.member", - "user_id": "@example:localhost" - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "JFLVteSvQc", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409666587265, - "type": "m.room.member", - "user_id": "@example:localhost" - } - ] - } - ] - } - -This returns all the room information the user is invited/joined on, as well as -all of the presences relevant for these rooms. This can be a LOT of data. You -may just want the most recent event for each room. This can be achieved by -applying query parameters to ``limit`` this request:: - - curl -XGET "http://localhost:8008/_matrix/client/api/v1/initialSync?limit=1&access_token=YOUR_ACCESS_TOKEN" - - { - "end": "s39_18_0", - "presence": [ - { - "content": { - "last_active_ago": 1279484, - "user_id": "@example:localhost" - }, - "type": "m.presence" - } - ], - "rooms": [ - { - "membership": "join", - "messages": { - "chunk": [ - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "JFLVteSvQc", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409666587265, - "type": "m.room.member", - "user_id": "@example:localhost" - } - ], - "end": "s39_18_0", - "start": "t10-30_18_0" - }, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state": [ - { - "content": { - "creator": "@example:localhost" - }, - "event_id": "dMUoqVTZca", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.create", - "user_id": "@example:localhost" - }, - { - "content": { - "@example:localhost": 10, - "default": 0 - }, - "event_id": "wAumPSTsWF", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.power_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "join_rule": "public" - }, - "event_id": "jrLVqKHKiI", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.join_rules", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 10 - }, - "event_id": "WpmTgsNWUZ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.add_state_level", - "user_id": "@example:localhost" - }, - { - "content": { - "level": 0 - }, - "event_id": "qUMBJyKsTQ", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.send_event_level", - "user_id": "@example:localhost" - }, - { - "content": { - "ban_level": 5, - "kick_level": 5 - }, - "event_id": "YAaDmKvoUW", - "required_power_level": 10, - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "", - "ts": 1409665585188, - "type": "m.room.ops_levels", - "user_id": "@example:localhost" - }, - { - "content": { - "membership": "invite" - }, - "event_id": "YjNuBKnPsb", - "membership": "invite", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@myfriend:localhost", - "ts": 1409666426819, - "type": "m.room.member", - "user_id": "@example:localhost" - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "JFLVteSvQc", - "membership": "join", - "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", - "state_key": "@example:localhost", - "ts": 1409666587265, - "type": "m.room.member", - "user_id": "@example:localhost" - } - ] - } - ] - } - -Getting live state ------------------- -Once you know which rooms the client has previously interacted with, you need to -listen for incoming events. This can be done like so:: - - curl -XGET "http://localhost:8008/_matrix/client/api/v1/events?access_token=YOUR_ACCESS_TOKEN" - - { - "chunk": [], - "end": "s39_18_0", - "start": "s39_18_0" - } - -This will block waiting for an incoming event, timing out after several seconds. -Even if there are no new events (as in the example above), there will be some -pagination stream response keys. The client should make subsequent requests -using the value of the ``"end"`` key (in this case ``s39_18_0``) as the ``from`` -query parameter e.g. ``http://localhost:8008/_matrix/client/api/v1/events?access -_token=YOUR_ACCESS_TOKEN&from=s39_18_0``. This value should be stored so when the -client reopens your app after a period of inactivity, you can resume from where -you got up to in the event stream. If it has been a long period of inactivity, -there may be LOTS of events waiting for the user. In this case, you may wish to -get all state instead and then resume getting live state from a newer end token. - -NB: The timeout can be changed by adding a ``timeout`` query parameter, which is -in milliseconds. A timeout of 0 will not block. - - -Example application -------------------- -The following example demonstrates registration and login, live event streaming, -creating and joining rooms, sending messages, getting member lists and getting -historical messages for a room. This covers most functionality of a messaging -application. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/example_app diff --git a/supporting-docs/howtos/2014-06-09-client-server.md b/supporting-docs/howtos/2014-06-09-client-server.md new file mode 100644 index 00000000..d62f86d7 --- /dev/null +++ b/supporting-docs/howtos/2014-06-09-client-server.md @@ -0,0 +1,11 @@ +--- +layout: project +title: Try Matrix Now! +categories: howtos +--- + + + + + + diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst deleted file mode 100644 index a8c8db48..00000000 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ /dev/null @@ -1,108 +0,0 @@ -Migrating from client-server API v1 -=================================== - -This guide assists developers of API clients that target the ``v1`` version of -the API to migrate their code to the later ``r0``. It does not aim to introduce -new concepts that were added in ``r0`` except where these replace things that -were removed since ``v1``. - -Updated Version In Path -======================= - -The new version of the API is ``r0``; this should be used in paths where -``v1`` used to appear. Additionally, the ``/api`` path component has now been -removed. API endpoint paths are now:: - - POST /_matrix/client/r0/register - GET /_matrix/client/r0/login - etc... - -New Registration and Login Endpoints -==================================== - -The ``r0`` version of the ``/register`` and ``/login`` endpoints is different -to the ``v1`` version. See the updated API documentation for details on how the -new API works. In brief, the changes are that the new version returns extra -information in the form of the ``params`` object, and that a sequence of -multiple calls may be statefully chained together by the ``session`` parameter. - -Additionally, whereas in ``v1`` the client performed a ``GET`` request to -discover the list of supported flows for ``/register``, in ``r0`` this is done -by sending a ``POST`` request with an empty data body. The ``/login`` endpoint -continues to use the ``GET`` method as before. - -Deprecated Endpoints -==================== - -The following endpoints are now deprecated and replaced by the ``/sync`` API:: - - /initialSync - /events - /rooms/:roomId/initialSync - -The new ``/sync`` API takes an optional ``since`` parameter to distinguish the -initial sync from subsequent updates for more events. - -The return value takes a different structure to that from the previous -``/initialSync`` API. For full details see the API documentation, but the -following summary may be useful to compare with ``v1``: - - * ``/initialSync`` returned a ``state`` key containing the most recent state - in the room, whereas the new ``/sync`` API's ``state`` corresponds to the - room state at the start of the returned timeline. This makes it easier for - clients to represent state changes that occur within the region of returned - timeline. - - * In ``/events``, if more events occurred since the ``since`` token than the - ``limit`` parameter allowed, then events from the start of this range were - returned and the client had to perform another fetch to incrementally obtain - more of them. In the ``/sync`` API the result always contains the most - recent events, creating a gap if this would be more events than the - requested limit. If this occurs then the client can use the ``prev_batch`` - token as a reference to obtaining more. - - * The ``state`` contained in the response to a ``/sync`` request that has a - ``since`` parameter will contain only keys that have changed since the - basis given in the ``since`` parameter, rather than containing a full set - values. - -The ``/initialSync`` API allowed a parameter called ``limit`` to limit the -number of events returned. To apply this limit to the new ``/sync`` API, you -can supply an ad-hoc filter:: - - GET .../sync?filter={"room":{"timeline":{"limit:$limit}}} - -There is no direct replacement for the per-room ``/rooms/:roomId/initialSync`` -endpoint, but the behaviour can be recreated by applying an ad-hoc filter using -the ``filter`` parameter to ``/sync`` that selects only the required room ID:: - - GET .../sync?filter={"room":{"rooms":[$room_id]}} - -However, the way that the new ``/sync`` API works should remove any need to do -this kind of query, in the situations where the ``v1`` API needed it. -Specifically, on joining a new room the initial information about that room is -sent in the next ``/sync`` batch, so it should not be necessary to query that -one room specially. - -The following endpoint is deprecated and has no direct replacement:: - - /events/:eventId - -However, if the client knows the room ID of the room that the event is in, it -can use the ``/rooms/:roomId/context/:eventId`` request to fetch the event -itself. By giving the ``limit`` parameter of ``0`` the client can save using -extra bandwidth by actually returning additional context events around the -requested one. - -Removed POST Endpoint -===================== - -The room message sending API endpoint in ``v1`` accepted both ``PUT`` and -``POST`` methods, where the client could specify a message ID in the ``PUT`` -path for de-duplication purposes, or have the server allocate one during -``POST``. In ``r0`` this latter form no longer exists. Clients will now have -to generate these IDs locally. - -The following URLs have therefore been removed:: - - POST .../rooms/:roomId/send/:messageType diff --git a/supporting-docs/howtos/client-server.rst b/supporting-docs/howtos/client-server.rst deleted file mode 100644 index 26119982..00000000 --- a/supporting-docs/howtos/client-server.rst +++ /dev/null @@ -1,387 +0,0 @@ -.. TODO kegan - Room config (specifically: message history, - public rooms). - -How to use the client-server API -================================ - -.. NOTE:: - The git version of this document is ``{{git_version}}`` - -This guide focuses on how the client-server APIs *provided by the reference -homeserver* can be used. Since this is specific to a homeserver -implementation, there may be variations in relation to registering/logging in -which are not covered in extensive detail in this guide. - -If you haven't already, get a homeserver up and running on -``https://localhost:8448``. - - -Accounts -======== -Before you can send and receive messages, you must **register** for an account. -If you already have an account, you must **login** into it. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/register_login - -Registration ------------- -The aim of registration is to get a user ID and access token which you will need -when accessing other APIs:: - - curl -XPOST -d '{"username":"example", "password":"wordpass", "auth": {"type":"m.login.dummy"}}' "https://localhost:8448/_matrix/client/r0/register" - - { - "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc", - "home_server": "localhost", - "user_id": "@example:localhost" - } - -NB: If a ``user`` is not specified, one will be randomly generated for you. -If you do not specify a ``password``, you will be unable to login to the account -if you forget the ``access_token``. - -Implementation note: The matrix specification does not enforce how users -register with a server. It just specifies the URL path and absolute minimum -keys. The reference homeserver uses a username/password to authenticate user, -but other homeservers may use different methods. This is why you need to -specify the ``type`` of method. - -Login ------ -The aim when logging in is to get an access token for your existing user ID:: - - curl -XGET "https://localhost:8448/_matrix/client/r0/login" - - { - "flows": [ - { - "type": "m.login.password" - } - ] - } - - curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "https://localhost:8448/_matrix/client/r0/login" - - { - "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd", - "home_server": "localhost", - "user_id": "@example:localhost" - } - -Implementation note: Different homeservers may implement different methods for -logging in to an existing account. In order to check that you know how to login -to this homeserver, you must perform a ``GET`` first and make sure you -recognise the login type. If you do not know how to login, you can -``GET /login/fallback`` which will return a basic webpage which you can use to -login. The reference homeserver implementation support username/password login, -but other homeservers may support different login methods (e.g. OAuth2). - - -Communicating -============= - -In order to communicate with another user, you must **create a room** with that -user and **send a message** to that room. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/create_room_send_msg - -Creating a room ---------------- -If you want to send a message to someone, you have to be in a room with them. To -create a room:: - - curl -XPOST -d '{"room_alias_name":"tutorial"}' "https://localhost:8448/_matrix/client/r0/createRoom?access_token=YOUR_ACCESS_TOKEN" - - { - "room_alias": "#tutorial:localhost", - "room_id": "!asfLdzLnOdGRkdPZWu:localhost" - } - -The "room alias" is a human-readable string which can be shared with other users -so they can join a room, rather than the room ID which is a randomly generated -string. You can have multiple room aliases per room. - -.. TODO(kegan) - How to add/remove aliases from an existing room. - - -Sending messages ----------------- -You can now send messages to this room:: - - curl -XPOST -d '{"msgtype":"m.text", "body":"hello"}' "https://localhost:8448/_matrix/client/r0/rooms/%21asfLdzLnOdGRkdPZWu:localhost/send/m.room.message?access_token=YOUR_ACCESS_TOKEN" - - { - "event_id": "YUwRidLecu" - } - -The event ID returned is a unique ID which identifies this message. - -NB: There are no limitations to the types of messages which can be exchanged. -The only requirement is that ``"msgtype"`` is specified. The Matrix -specification outlines the following standard types: ``m.text``, ``m.image``, -``m.audio``, ``m.video``, ``m.location``, ``m.emote``. See the specification for -more information on these types. - -Users and rooms -=============== - -Each room can be configured to allow or disallow certain rules. In particular, -these rules may specify if you require an **invitation** from someone already in -the room in order to **join the room**. In addition, you may also be able to -join a room **via a room alias** if one was set up. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/room_memberships - -Inviting a user to a room -------------------------- -You can directly invite a user to a room like so:: - - curl -XPOST -d '{"user_id":"@myfriend:localhost"}' "https://localhost:8448/_matrix/client/r0/rooms/%21asfLdzLnOdGRkdPZWu:localhost/invite?access_token=YOUR_ACCESS_TOKEN" - -This informs ``@myfriend:localhost`` of the room ID -``!CvcvRuDYDzTOzfKKgh:localhost`` and allows them to join the room. - -Joining a room via an invite ----------------------------- -If you receive an invite, you can join the room:: - - curl -XPOST -d '{}' "https://localhost:8448/_matrix/client/r0/rooms/%21asfLdzLnOdGRkdPZWu:localhost/join?access_token=YOUR_ACCESS_TOKEN" - -NB: Only the person invited (``@myfriend:localhost``) can change the membership -state to ``"join"``. Repeatedly joining a room does nothing. - -Joining a room via an alias ---------------------------- -Alternatively, if you know the room alias for this room and the room config -allows it, you can directly join a room via the alias:: - - curl -XPOST -d '{}' "https://localhost:8448/_matrix/client/r0/join/%21asfLdzLnOdGRkdPZWu:localhost?access_token=YOUR_ACCESS_TOKEN" - - { - "room_id": "!CvcvRuDYDzTOzfKKgh:localhost" - } - -You will need to use the room ID when sending messages, not the room alias. - -NB: If the room is configured to be an invite-only room, you will still require -an invite in order to join the room even though you know the room alias. As a -result, it is more common to see a room alias in relation to a public room, -which do not require invitations. - -Getting events -============== -An event is some interesting piece of data that a client may be interested in. -It can be a message in a room, a room invite, etc. There are many different ways -of getting events, depending on what the client already knows. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/event_stream - -Getting all state ------------------ -If the client doesn't know any information on the rooms the user is -invited/joined on, they can get all the user's state for all rooms:: - - curl -XGET "https://localhost:8448/_matrix/client/r0/sync?access_token=YOUR_ACCESS_TOKEN" - - { - "account_data": { - "events": [ - { - ... - } - ] - }, - "next_batch": "s9_3_0_1_1_1", - "presence": { - "events": [ - { - "content": { - "currently_active": true, - "last_active_ago": 19, - "presence": "online" - }, - "sender": "@example:localhost", - "type": "m.presence" - } - ] - }, - "rooms": { - "invite": {}, - "join": { - "!asfLdzLnOdGRkdPZWu:localhost": { - "account_data": { - "events": [] - }, - "ephemeral": { - "events": [] - }, - "state": { - "events": [] - }, - "timeline": { - "events": [ - { - "content": { - "creator": "@example:localhost" - }, - "event_id": "$14606534990LhqHt:localhost", - "origin_server_ts": 1460653499699, - "sender": "@example:localhost", - "state_key": "", - "type": "m.room.create", - "unsigned": { - "age": 239192 - } - }, - { - "content": { - "avatar_url": null, - "displayname": null, - "membership": "join" - }, - "event_id": "$14606534991nsZKk:localhost", - "membership": "join", - "origin_server_ts": 1460653499727, - "sender": "@example:localhost", - "state_key": "@example:localhost", - "type": "m.room.member", - "unsigned": { - "age": 239164 - } - }, - ... - ], - "limited": false, - "prev_batch": "s9_3_0_1_1_1" - }, - "unread_notifications": {} - } - }, - "leave": {} - } - } - -This returns all the room information the user is invited/joined on, as well as -all of the presences relevant for these rooms. This can be a LOT of data. You -may just want the most recent event for each room. This can be achieved by -applying a filter that asks for a limit of 1 timeline event per room:: - - curl --globoff -XGET "https://localhost:8448/_matrix/client/r0/sync?filter={'room':{'timeline':{'limit':1}}}&access_token=YOUR_ACCESS_TOKEN" - - { - ... - "rooms": { - "invite": {}, - "join": { - "!asfLdzLnOdGRkdPZWu:localhost": { - ... - "timeline": { - "events": [ - { - "content": { - "body": "hello", - "msgtype": "m.text" - }, - "event_id": "$14606535757KCGXo:localhost", - "origin_server_ts": 1460653575105, - "sender": "@example:localhost", - "type": "m.room.message", - "unsigned": { - "age": 800348 - } - } - ], - "limited": true, - "prev_batch": "t8-8_7_0_1_1_1" - }, - "unread_notifications": {} - } - }, - "leave": {} - } - } - -(additionally we have to ask ``curl`` not to try to interpret any ``{}`` -characters in the URL, which is what the ``--globoff`` option is for) - -Getting live state ------------------- -In the response to this ``sync`` request the server includes a token that can -be used to obtain updates since this point under the object key ``next_batch``. -To use this token, specify its value as the ``since`` parameter to another -``/sync`` request.:: - - curl -XGET "https://localhost:8448/_matrix/client/r0/sync?since=s9_7_0_1_1_1&access_token=YOUR_ACCESS_TOKEN" - - { - "account_data": { - "events": [] - }, - "next_batch": "s9_9_0_1_1_1", - "presence": { - "events": [ - { - "content": { - "currently_active": true, - "last_active_ago": 12, - "presence": "online" - }, - "sender": "@example:localhost", - "type": "m.presence" - } - ] - }, - "rooms": { - "invite": {}, - "join": {}, - "leave": {} - } - } - -By default this request will not wait in the server, always returning a value -even if nothing interesting happened. However, by applying the ``timeout`` -query parameter, which gives a duration in miliseconds, we can ask the server -to wait for up to that amount of time before it returns. If no interesting -events have happened since then, the response will be relatively empty.:: - - curl -XGET "https://localhost:8448/_matrix/client/r0/sync?since=s9_13_0_1_1_1&access_token=YOUR_ACCESS_TOKEN" - { - "account_data": { - "events": [] - }, - "next_batch": "s9_13_0_1_1_1", - "presence": { - "events": [] - }, - "rooms": { - "invite": {}, - "join": {}, - "leave": {} - } - } - -Example application -------------------- -The following example demonstrates registration and login, live event streaming, -creating and joining rooms, sending messages, getting member lists and getting -historical messages for a room. This covers most functionality of a messaging -application. - -.. NOTE:: - `Try out the fiddle`__ - - .. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/matrix-doc/tree/master/supporting-docs/howtos/jsfiddles/example_app diff --git a/supporting-docs/projects/2015-04-02-vector-ios.md b/supporting-docs/projects/2015-04-02-vector-ios.md deleted file mode 100644 index 8cf097d7..00000000 --- a/supporting-docs/projects/2015-04-02-vector-ios.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: project -title: Try Matrix Now! -categories: projects client --- - - - - - -