|
@@ -53,7 +53,7 @@ As I quickly hinted at, a room can be either public or private. Public rooms can
|
53
|
53
|
|
54
|
54
|
Now that we know what a room is, let's talk about what's passing inside of one. Earlier, I've been talking about messages, which are actually called "events". Technically speaking, a Matrix event is a JSON object that's sent in a room and dispatched to all other members of the room. It, of course, has an ID that's generated by the homeserver hosting the user who sent the message, taking the general form we saw earlier and the `$` sigil character. This JSON has metadata, such as a class name to identify different event types, an author, a creation timestamp, etc. It basically looks like this:
|
55
|
55
|
|
56
|
|
-{{< highlight json "linenos=table" >}}
|
|
56
|
+{{< highlight json >}}
|
57
|
57
|
{
|
58
|
58
|
"origin_server_ts": 1526072700313,
|
59
|
59
|
"sender": "@Alice:matrix.alice.tld",
|
|
@@ -107,7 +107,7 @@ Note that every endpoint in the Matrix spec always starts with `/_matrix/`.
|
107
|
107
|
|
108
|
108
|
The request body is a JSON which takes the following form:
|
109
|
109
|
|
110
|
|
-{{< highlight json "linenos=table" >}}
|
|
110
|
+{{< highlight json >}}
|
111
|
111
|
{
|
112
|
112
|
"username": "Alice",
|
113
|
113
|
"password": "1L0v3M4tr!x",
|
|
@@ -118,7 +118,7 @@ Here, the `username` and `password` properties are exactly what you think it is.
|
118
|
118
|
|
119
|
119
|
Fire this request. You'll now get a `401` status code along with some JSON, which looks like this:
|
120
|
120
|
|
121
|
|
-{{< highlight json "linenos=table" >}}
|
|
121
|
+{{< highlight json >}}
|
122
|
122
|
{
|
123
|
123
|
"flows": [
|
124
|
124
|
{
|
|
@@ -139,7 +139,7 @@ Fire this request. You'll now get a `401` status code along with some JSON, whic
|
139
|
139
|
|
140
|
140
|
Now, this enpoint uses a part of the spec called the [User-Interactive Authentication API](https://matrix.org/docs/spec/client_server/r0.3.0.html#user-interactive-authentication-api). This means that authentication can be seen as flows of consecutive stages. That's exactly what we have here: two flows, each containing one stage. This example is a very simple one, but it can get quite more complex, such as:
|
141
|
141
|
|
142
|
|
-{{< highlight json "linenos=table" >}}
|
|
142
|
+{{< highlight json >}}
|
143
|
143
|
{
|
144
|
144
|
"flows": [
|
145
|
145
|
{
|
|
@@ -169,7 +169,7 @@ Because I want to keep it as simple as possible here, let's get back at our init
|
169
|
169
|
|
170
|
170
|
To register against this stage, we'll only add a few lines to our initial request's JSON:
|
171
|
171
|
|
172
|
|
-{{< highlight json "linenos=table" >}}
|
|
172
|
+{{< highlight json >}}
|
173
|
173
|
{
|
174
|
174
|
"auth": {
|
175
|
175
|
"type": "m.login.dummy",
|
|
@@ -182,7 +182,7 @@ To register against this stage, we'll only add a few lines to our initial reques
|
182
|
182
|
|
183
|
183
|
Note that the value to the `session` property in the newly added `auth` object is the value from `sessions` taken from the homeserver's response to our intial request. This `auth` object will tell the homeserver that this request is a follow-up to the initial request, using the stage `m.login.dummy`. The homeserver will automatically recognise the flow we're using, and will succeed (because we use `m.login.dummy`), returning this JSON along with a `200` status code:
|
184
|
184
|
|
185
|
|
-{{< highlight json "linenos=table" >}}
|
|
185
|
+{{< highlight json >}}
|
186
|
186
|
{
|
187
|
187
|
"access_token": "olic0yeVa1pore2Kie4Wohsh",
|
188
|
188
|
"device_id": "FOZLAWNKLD",
|
|
@@ -208,7 +208,7 @@ There are a few JSON parameters available which I won't cover here because none
|
208
|
208
|
|
209
|
209
|
Before responding, the homeserver will create the room, fire a few state events in it (such as the initial `m.room.create` state event or a join event for your user). It should then respond with a `200` status code and a JSON body looking like this:
|
210
|
210
|
|
211
|
|
-{{< highlight json "linenos=table" >}}
|
|
211
|
+{{< highlight json >}}
|
212
|
212
|
{
|
213
|
213
|
"room_id": "!RtZiWTovChPysCUIgn:matrix.project.tld"
|
214
|
214
|
}
|
|
@@ -222,7 +222,7 @@ Browsing the room's state is completely useless at this stage, but let's do it a
|
222
|
222
|
|
223
|
223
|
The request should return a JSON array containing state events such as:
|
224
|
224
|
|
225
|
|
-{{< highlight json "linenos=table" >}}
|
|
225
|
+{{< highlight json >}}
|
226
|
226
|
{
|
227
|
227
|
"age": 654742,
|
228
|
228
|
"content": {
|
|
@@ -246,7 +246,7 @@ The body for our request is the event's content object.
|
246
|
246
|
|
247
|
247
|
Let's create a `tld.project.foo` event with `bar` as its state key, and `{"baz": "qux"}` as its content. To achieve that, let's send a `PUT` request to `/_matrix/client/r0/rooms/!RtZiWTovChPysCUIgn:matrix.project.tld/state/tld.project.foo/bar?access_token=olic0yeVa1pore2Kie4Wohsh` (from which I've stripped the protocol scheme and FQDN so it doesn't appear too in the post) with the fillowing content:
|
248
|
248
|
|
249
|
|
-{{< highlight json "linenos=table" >}}
|
|
249
|
+{{< highlight json >}}
|
250
|
250
|
{
|
251
|
251
|
"baz": "qux"
|
252
|
252
|
}
|
|
@@ -256,7 +256,7 @@ The homeserver then responds with an object only containing an `event_id` proper
|
256
|
256
|
|
257
|
257
|
If we retry the request we previously made to retrieve the whole room state, we can now see our event:
|
258
|
258
|
|
259
|
|
-{{< highlight json "linenos=table" >}}
|
|
259
|
+{{< highlight json >}}
|
260
|
260
|
{
|
261
|
261
|
"age": 58357,
|
262
|
262
|
"content": {
|
|
@@ -292,7 +292,7 @@ So far, Alice has registered on the homeserver and created her room, but she fee
|
292
|
292
|
|
293
|
293
|
Inviting someone into a room is also quite simple, and only requires a `POST` request on the [`/_matrix/client/r0/rooms/{roomId}/invite`](https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-rooms-roomid-invite) endpoint. The request's body must contain the invited Matrix ID as such:
|
294
|
294
|
|
295
|
|
-{{< highlight json "linenos=table" >}}
|
|
295
|
+{{< highlight json >}}
|
296
|
296
|
{
|
297
|
297
|
"user_id": "@Bob:matrix.bob.tld"
|
298
|
298
|
}
|
|
@@ -304,7 +304,7 @@ If all went well, the homeserver should respond with a `200` status code and an
|
304
|
304
|
|
305
|
305
|
In the next request on the [`/_matrix/client/r0/sync`](https://matrix.org/docs/spec/client_server/r0.3.0.html#get-matrix-client-r0-sync) he'll made, Bob will now see an `invite` object inside the `rooms` one contaning the invite Alice sent him, containing a few events including the invite event:
|
306
|
306
|
|
307
|
|
-{{< highlight json "linenos=table" >}}
|
|
307
|
+{{< highlight json >}}
|
308
|
308
|
{
|
309
|
309
|
"invite": {
|
310
|
310
|
"!RtZiWTovChPysCUIgn:matrix.project.tld": {
|