More formatting, more clarity.

This commit is contained in:
Kegan Dougal 2014-08-19 14:25:03 +01:00
parent 77f1cc7d6d
commit e636e8799e

View File

@ -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.