archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update v1 /initialSync + /events examples to use r0 /sync instead

Browse Source
pull/977/head
Paul "LeoNerd" Evans 9 years ago
parent 079a963bc5
commit a064d37f64
1 changed files with 160 additions and 415 deletions
Show Stats Download Patch File Download Diff File

559
supporting-docs/howtos/client-server.rst
Unescape Escape View File

@ -195,439 +195,184 @@ Getting all state
If the client doesn't know any information on the rooms the user is 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:: invited/joined on, they can get all the user's state for all rooms::
curl -XGET "https://localhost:8008/_matrix/client/api/v1/initialSync?access_token=YOUR_ACCESS_TOKEN" curl -XGET "https://localhost:8008/_matrix/client/r0/sync?access_token=YOUR_ACCESS_TOKEN"
{ {
"end": "s39_18_0", "account_data": {
"presence": [ "events": [
{ {
"content": { ...
"last_active_ago": 1061436, }
"user_id": "@example:localhost" ]
}, },
"type": "m.presence" "next_batch": "s9_3_0_1_1_1",
} "presence": {
], "events": [
"rooms": [ {
{ "content": {
"membership": "join", "currently_active": true,
"messages": { "last_active_ago": 19,
"chunk": [ "presence": "online"
{
"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"
}, },
{ "sender": "@example:localhost:8080",
"content": { "type": "m.presence"
"join_rule": "public" }
}, ]
"event_id": "jrLVqKHKiI", },
"required_power_level": 10, "rooms": {
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "invite": {},
"state_key": "", "join": {
"ts": 1409665585188, "!asfLdzLnOdGRkdPZWu:localhost:8080": {
"type": "m.room.join_rules", "account_data": {
"user_id": "@example:localhost" "events": []
}, },
{ "ephemeral": {
"content": { "events": []
"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"
}, },
{ "state": {
"content": { "events": []
"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"
}, },
{ "timeline": {
"content": { "events": [
"ban_level": 5, {
"kick_level": 5 "content": {
}, "creator": "@example:localhost:8080"
"event_id": "YAaDmKvoUW", },
"required_power_level": 10, "event_id": "$14606534990LhqHt:localhost:8080",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "origin_server_ts": 1460653499699,
"state_key": "", "sender": "@example:localhost:8080",
"ts": 1409665585188, "state_key": "",
"type": "m.room.ops_levels", "type": "m.room.create",
"user_id": "@example:localhost" "unsigned": {
}, "age": 239192
{ }
"content": { },
"membership": "invite" {
}, "content": {
"event_id": "YjNuBKnPsb", "avatar_url": null,
"membership": "invite", "displayname": null,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "membership": "join"
"state_key": "@myfriend:localhost", },
"ts": 1409666426819, "event_id": "$14606534991nsZKk:localhost:8080",
"type": "m.room.member", "membership": "join",
"user_id": "@example:localhost" "origin_server_ts": 1460653499727,
"sender": "@example:localhost:8080",
"state_key": "@example:localhost:8080",
"type": "m.room.member",
"unsigned": {
"age": 239164
}
},
...
],
"limited": false,
"prev_batch": "s9_3_0_1_1_1"
}, },
{ "unread_notifications": {}
"content": { }
"avatar_url": null, },
"displayname": null, "leave": {}
"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 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 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 may just want the most recent event for each room. This can be achieved by
applying query parameters to ``limit`` this request:: applying a filter that asks for a limit of 1 timeline event per room::
curl -XGET "https://localhost:8008/_matrix/client/api/v1/initialSync?limit=1&access_token=YOUR_ACCESS_TOKEN" curl --globoff -XGET "https://localhost:8008/_matrix/client/r0/sync?filter={'room':{'timeline':{'limit':1}}}&access_token=YOUR_ACCESS_TOKEN"
{ {
"end": "s39_18_0", ...
"presence": [ "rooms": {
{ "invite": {},
"content": { "join": {
"last_active_ago": 1279484, "!asfLdzLnOdGRkdPZWu:localhost:8080": {
"user_id": "@example:localhost" ...
}, "timeline": {
"type": "m.presence" "events": [
} {
], "content": {
"rooms": [ "body": "hello",
{ "msgtype": "m.text"
"membership": "join", },
"messages": { "event_id": "$14606535757KCGXo:localhost:8080",
"chunk": [ "origin_server_ts": 1460653575105,
{ "sender": "@example:localhost:8080",
"content": { "type": "m.room.message",
"avatar_url": null, "unsigned": {
"displayname": null, "age": 800348
"membership": "join" }
}, }
"event_id": "JFLVteSvQc", ],
"membership": "join", "limited": true,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "prev_batch": "t8-8_7_0_1_1_1"
"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"
}, },
{ "unread_notifications": {}
"content": { }
"ban_level": 5, },
"kick_level": 5 "leave": {}
}, }
"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"
}
]
}
]
} }
(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 Getting live state
------------------ ------------------
Once you know which rooms the client has previously interacted with, you need to In the response to this ``sync`` request the server includes a token that can
listen for incoming events. This can be done like so:: 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:8008/_matrix/client/api/v1/events?access_token=YOUR_ACCESS_TOKEN" curl -XGET "https://localhost:8008/_matrix/client/r0/sync?since=s9_7_0_1_1_1&access_token=YOUR_ACCESS_TOKEN"
{ {
"chunk": [], "account_data": {
"end": "s39_18_0", "events": []
"start": "s39_18_0" },
"next_batch": "s9_9_0_1_1_1",
"presence": {
"events": [
{
"content": {
"currently_active": true,
"last_active_ago": 12,
"presence": "online"
},
"sender": "@example:localhost:8080",
"type": "m.presence"
}
]
},
"rooms": {
"invite": {},
"join": {},
"leave": {}
}
} }
This will block waiting for an incoming event, timing out after several seconds. By default this request will not wait in the server, always returning a value
Even if there are no new events (as in the example above), there will be some even if nothing interesting happened. However, by applying the ``timeout``
pagination stream response keys. The client should make subsequent requests query parameter, which gives a duration in miliseconds, we can ask the server
using the value of the ``"end"`` key (in this case ``s39_18_0``) as the ``from`` to wait for up to that amount of time before it returns. If no interesting
query parameter e.g. ``https://localhost:8008/_matrix/client/api/v1/events?access events have happened since then, the response will be relatively empty.::
_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.
curl -XGET "https://localhost:8008/_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 Example application
------------------- -------------------

Write Preview
Loading…
Cancel
Save