mirror of
https://git.anonymousland.org/anonymousland/synapse.git
synced 2024-12-26 11:59:21 -05:00
More formatting, more clarity.
This commit is contained in:
parent
77f1cc7d6d
commit
e636e8799e
@ -1,13 +1,20 @@
|
|||||||
How to use the client-server API
|
|
||||||
================================
|
|
||||||
|
|
||||||
TODO(kegan): Tweak joinalias API keys/path? Event stream historical > live needs
|
TODO(kegan): Tweak joinalias API keys/path? Event stream historical > live needs
|
||||||
a token (currently doesn't). im/sync responses include outdated event formats
|
a token (currently doesn't). im/sync responses include outdated event formats
|
||||||
(room membership change messages). Room config (specifically: message history,
|
(room membership change messages). Room config (specifically: message history,
|
||||||
public rooms)
|
public rooms). /register seems super simplistic compared to /login, maybe it
|
||||||
|
would be better if /register used the same technique as /login?
|
||||||
|
|
||||||
|
|
||||||
If you haven't already, get a home server up and running on localhost:8080.
|
How to use the client-server API
|
||||||
|
================================
|
||||||
|
|
||||||
|
This guide focuses on how the client-server APIs *provided by the reference
|
||||||
|
home server* can be used. Since this is specific to a home server
|
||||||
|
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 home server up and running on
|
||||||
|
``http://localhost:8080``.
|
||||||
|
|
||||||
|
|
||||||
Accounts
|
Accounts
|
||||||
@ -32,6 +39,11 @@ NB: If a user ID 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
|
you do not specify a password, you will be unable to login to the account if you
|
||||||
forget the access token.
|
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 home server uses a username/password to authenticate user,
|
||||||
|
but other home servers may use different methods.
|
||||||
|
|
||||||
Login
|
Login
|
||||||
-----
|
-----
|
||||||
The aim of login is to get an access token for your existing user ID::
|
The aim of login is to get an access token for your existing user ID::
|
||||||
@ -50,11 +62,13 @@ The aim of login is to get an access token for your existing user ID::
|
|||||||
"user_id": "@example:localhost"
|
"user_id": "@example:localhost"
|
||||||
}
|
}
|
||||||
|
|
||||||
NB: Different home servers may implement different methods for logging in to an
|
Implementation note: Different home servers may implement different methods for
|
||||||
existing account. In order to check that you know how to login to this home
|
logging in to an existing account. In order to check that you know how to login
|
||||||
server, you must perform a GET first and make sure you recognise the type. If
|
to this home server, you must perform a ``GET`` first and make sure you
|
||||||
you do not know how to login, you can GET /login/fallback which will return a
|
recognise the login type. If you do not know how to login, you can
|
||||||
basic webpage which you can use to login.
|
``GET /login/fallback`` which will return a basic webpage which you can use to
|
||||||
|
login. The reference home server implementation support username/password login,
|
||||||
|
but other home servers may support different login methods (e.g. OAuth2).
|
||||||
|
|
||||||
|
|
||||||
Communicating
|
Communicating
|
||||||
@ -89,7 +103,7 @@ You can now send messages to this room::
|
|||||||
curl -XPUT -d '{"msgtype":"m.text", "body":"hello"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/messages/%40example%3Alocalhost/msgid1?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
|
curl -XPUT -d '{"msgtype":"m.text", "body":"hello"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/messages/%40example%3Alocalhost/msgid1?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
|
||||||
|
|
||||||
NB: There are no limitations to the types of messages which can be exchanged.
|
NB: There are no limitations to the types of messages which can be exchanged.
|
||||||
The only requirement is that 'msgtype' is specified.
|
The only requirement is that ``'msgtype'`` is specified.
|
||||||
|
|
||||||
NB: Depending on the room config, users who join the room may be able to see
|
NB: Depending on the room config, users who join the room may be able to see
|
||||||
message history from before they joined.
|
message history from before they joined.
|
||||||
@ -108,8 +122,8 @@ You can directly invite a user to a room like so::
|
|||||||
|
|
||||||
curl -XPUT -d '{"membership":"invite"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
|
curl -XPUT -d '{"membership":"invite"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
|
||||||
|
|
||||||
This informs @myfriend:localhost of the room ID !CvcvRuDYDzTOzfKKgh:localhost
|
This informs ``@myfriend:localhost`` of the room ID
|
||||||
and allows them to join the room.
|
``!CvcvRuDYDzTOzfKKgh:localhost`` and allows them to join the room.
|
||||||
|
|
||||||
Joining a room via an invite
|
Joining a room via an invite
|
||||||
----------------------------
|
----------------------------
|
||||||
@ -118,8 +132,8 @@ join::
|
|||||||
|
|
||||||
curl -XPUT -d '{"membership":"join"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
|
curl -XPUT -d '{"membership":"join"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
|
||||||
|
|
||||||
NB: Only the person invited (@myfriend:localhost) can change the membership
|
NB: Only the person invited (``@myfriend:localhost``) can change the membership
|
||||||
state to 'join'.
|
state to ``'join'``.
|
||||||
|
|
||||||
Joining a room via an alias
|
Joining a room via an alias
|
||||||
---------------------------
|
---------------------------
|
||||||
@ -257,13 +271,14 @@ listen for incoming events. This can be done like so::
|
|||||||
}
|
}
|
||||||
|
|
||||||
This will block waiting for an incoming event, timing out after several seconds.
|
This will block waiting for an incoming event, timing out after several seconds.
|
||||||
A client should repeatedly make requests with the "from" query parameter with
|
A client should repeatedly make requests with the ``from`` query parameter with
|
||||||
the value of "end" (in this case "215"). This value should be stored so when the
|
the value of ``end`` (in this case ``215``). This value should be stored so when
|
||||||
client reopens your app after a period of inactivity, you can resume from where
|
the client reopens your app after a period of inactivity, you can resume from
|
||||||
you got up to in the event stream. If it has been a long period of inactivity,
|
where you got up to in the event stream. If it has been a long period of
|
||||||
there may be LOTS of events waiting for you. In this case, you may wish to get
|
inactivity, there may be LOTS of events waiting for you. In this case, you may
|
||||||
all state instead and then resume getting live state from a newer end token.
|
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
|
NB: The timeout can be changed by adding a ``timeout`` query parameter, which is
|
||||||
in milliseconds. A timeout of 0 will not block.
|
in milliseconds. A timeout of 0 will not block.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user