diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/client-server/howto.rst | 22 | ||||
| -rw-r--r-- | docs/client-server/specification.rst | 4 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/directory | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/events | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/login | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/presence | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/profile | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/registration | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/rooms | 82 | ||||
| -rw-r--r-- | docs/server-server/specification.rst | 2 | ||||
| -rw-r--r-- | docs/specification.rst | 162 |
11 files changed, 185 insertions, 99 deletions
diff --git a/docs/client-server/howto.rst b/docs/client-server/howto.rst index 9ef4cb5f78..3660c73d36 100644 --- a/docs/client-server/howto.rst +++ b/docs/client-server/howto.rst @@ -30,7 +30,7 @@ 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_id":"example", "password":"wordpass"}' "http://localhost:8080/matrix/client/api/v1/register" + curl -XPOST -d '{"user_id":"example", "password":"wordpass"}' "http://localhost:8080/_matrix/client/api/v1/register" { "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc", @@ -51,13 +51,13 @@ Login ----- The aim when logging in is to get an access token for your existing user ID:: - curl -XGET "http://localhost:8080/matrix/client/api/v1/login" + curl -XGET "http://localhost:8080/_matrix/client/api/v1/login" { "type": "m.login.password" } - curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "http://localhost:8080/matrix/client/api/v1/login" + curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "http://localhost:8080/_matrix/client/api/v1/login" { "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd", @@ -87,7 +87,7 @@ 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:8080/matrix/client/api/v1/rooms?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd" + curl -XPOST -d '{"room_alias_name":"tutorial"}' "http://localhost:8080/_matrix/client/api/v1/rooms?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd" { "room_alias": "#tutorial:localhost", @@ -105,7 +105,7 @@ Sending messages ---------------- 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. The only requirement is that ``"msgtype"`` is specified. @@ -127,7 +127,7 @@ Inviting a user to a room ------------------------- 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`` and allows them to join the room. @@ -137,7 +137,7 @@ Joining a room via an invite If you receive an invite, you can join the room by changing the membership to 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 state to ``"join"``. @@ -147,7 +147,7 @@ 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 -XPUT -d '{}' "http://localhost:8080/matrix/client/api/v1/join/%23tutorial%3Alocalhost?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK" + curl -XPUT -d '{}' "http://localhost:8080/_matrix/client/api/v1/join/%23tutorial%3Alocalhost?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK" { "room_id": "!CvcvRuDYDzTOzfKKgh:localhost" @@ -173,7 +173,7 @@ 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:8080/matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK" + curl -XGET "http://localhost:8080/_matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK" [ { @@ -236,7 +236,7 @@ all of the messages and feedback for these rooms. This can be a LOT of data. You may just want the most recent message for each room. This can be achieved by applying pagination stream parameters to this request:: - curl -XGET "http://localhost:8080/matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END&to=START&limit=1" + curl -XGET "http://localhost:8080/_matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END&to=START&limit=1" [ { @@ -271,7 +271,7 @@ 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:8080/matrix/client/api/v1/events?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END" + curl -XGET "http://localhost:8080/_matrix/client/api/v1/events?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END" { "chunk": [], diff --git a/docs/client-server/specification.rst b/docs/client-server/specification.rst index 4c1a3d4456..ee8bb5c420 100644 --- a/docs/client-server/specification.rst +++ b/docs/client-server/specification.rst @@ -306,11 +306,11 @@ POST requests MUST be submitted as application/json. All paths MUST be namespaced by the version of the API being used. This should be: -/matrix/client/api/v1 +/_matrix/client/api/v1 All REST paths in this section MUST be prefixed with this. E.g. REST Path: /rooms/$room_id - Absolute Path: /matrix/client/api/v1/rooms/$room_id + Absolute Path: /_matrix/client/api/v1/rooms/$room_id Registration ============ diff --git a/docs/client-server/swagger_matrix/directory b/docs/client-server/swagger_matrix/directory index 3f3bef9c11..98109a0fbc 100644 --- a/docs/client-server/swagger_matrix/directory +++ b/docs/client-server/swagger_matrix/directory @@ -1,7 +1,7 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "resourcePath": "/directory", "produces": [ "application/json" diff --git a/docs/client-server/swagger_matrix/events b/docs/client-server/swagger_matrix/events index ca69d34db5..d22c68cc78 100644 --- a/docs/client-server/swagger_matrix/events +++ b/docs/client-server/swagger_matrix/events @@ -1,7 +1,7 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "resourcePath": "/events", "produces": [ "application/json" diff --git a/docs/client-server/swagger_matrix/login b/docs/client-server/swagger_matrix/login index 4410d3c887..8cc598b3c1 100644 --- a/docs/client-server/swagger_matrix/login +++ b/docs/client-server/swagger_matrix/login @@ -40,7 +40,7 @@ "path": "/login" } ], - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "consumes": [ "application/json" ], diff --git a/docs/client-server/swagger_matrix/presence b/docs/client-server/swagger_matrix/presence index 1b4c7323aa..d52ce2164a 100644 --- a/docs/client-server/swagger_matrix/presence +++ b/docs/client-server/swagger_matrix/presence @@ -1,7 +1,7 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "resourcePath": "/presence", "produces": [ "application/json" diff --git a/docs/client-server/swagger_matrix/profile b/docs/client-server/swagger_matrix/profile index 1ebde62e20..188259fa3d 100644 --- a/docs/client-server/swagger_matrix/profile +++ b/docs/client-server/swagger_matrix/profile @@ -1,7 +1,7 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "resourcePath": "/profile", "produces": [ "application/json" diff --git a/docs/client-server/swagger_matrix/registration b/docs/client-server/swagger_matrix/registration index ccd542d11e..2048aec1d2 100644 --- a/docs/client-server/swagger_matrix/registration +++ b/docs/client-server/swagger_matrix/registration @@ -37,7 +37,7 @@ "path": "/register" } ], - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "consumes": [ "application/json" ], diff --git a/docs/client-server/swagger_matrix/rooms b/docs/client-server/swagger_matrix/rooms index bb49ec5a6a..7d3341f097 100644 --- a/docs/client-server/swagger_matrix/rooms +++ b/docs/client-server/swagger_matrix/rooms @@ -1,7 +1,7 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://localhost:8080/matrix/client/api/v1", + "basePath": "http://localhost:8080/_matrix/client/api/v1", "resourcePath": "/rooms", "produces": [ "application/json" @@ -14,12 +14,12 @@ }, "apis": [ { - "path": "/rooms/{roomId}/send/{eventType}/{txnId}", + "path": "/rooms/{roomId}/send/{eventType}", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Send a generic non-state event to this room.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/{eventType}", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "EventId", "nickname": "send_non_state_event", "consumes": [ @@ -46,13 +46,6 @@ "required": true, "type": "string", "paramType": "path" - }, - { - "name": "txnId", - "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", - "required": true, - "type": "string", - "paramType": "path" } ] } @@ -104,12 +97,12 @@ ] }, { - "path": "/rooms/{roomId}/send/m.room.message/{txnId}", + "path": "/rooms/{roomId}/send/m.room.message", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Send a message in this room.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/m.room.message", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "EventId", "nickname": "send_message", "consumes": [ @@ -129,13 +122,6 @@ "required": true, "type": "string", "paramType": "path" - }, - { - "name": "txnId", - "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", - "required": true, - "type": "string", - "paramType": "path" } ] } @@ -195,12 +181,12 @@ ] }, { - "path": "/rooms/{roomId}/send/m.room.message.feedback/{txnId}", + "path": "/rooms/{roomId}/send/m.room.message.feedback", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Send feedback to a message.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/m.room.message.feedback", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "EventId", "nickname": "send_feedback", "consumes": [ @@ -220,13 +206,6 @@ "required": true, "type": "string", "paramType": "path" - }, - { - "name": "txnId", - "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", - "required": true, - "type": "string", - "paramType": "path" } ], "responseMessages": [ @@ -239,12 +218,12 @@ ] }, { - "path": "/rooms/{roomId}/invite/{txnId}", + "path": "/rooms/{roomId}/invite", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Invite a user to this room.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/invite", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "void", "nickname": "invite", "consumes": [ @@ -259,13 +238,6 @@ "paramType": "path" }, { - "name": "txnId", - "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", - "required": false, - "type": "string", - "paramType": "path" - }, - { "name": "body", "description": "The user to invite.", "required": true, @@ -277,12 +249,12 @@ ] }, { - "path": "/rooms/{roomId}/join/{txnId}", + "path": "/rooms/{roomId}/join", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Join this room.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/join", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "void", "nickname": "join_room", "consumes": [ @@ -295,25 +267,18 @@ "required": true, "type": "string", "paramType": "path" - }, - { - "name": "txnId", - "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", - "required": false, - "type": "string", - "paramType": "path" } ] } ] }, { - "path": "/rooms/{roomId}/leave/{txnId}", + "path": "/rooms/{roomId}/leave", "operations": [ { - "method": "PUT", + "method": "POST", "summary": "Leave this room.", - "notes": "This operation can also be done as a POST to /rooms/{roomId}/leave", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", "type": "void", "nickname": "leave", "consumes": [ @@ -326,13 +291,6 @@ "required": true, "type": "string", "paramType": "path" - }, - { - "name": "txnId", - "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", - "required": false, - "type": "string", - "paramType": "path" } ] } @@ -476,7 +434,7 @@ "parameters": [ { "name": "body", - "description": "The desired configuration for the room.", + "description": "The desired configuration for the room. This operation can also be done as a PUT by suffixing /{txnId}.", "required": true, "type": "RoomConfig", "paramType": "body" diff --git a/docs/server-server/specification.rst b/docs/server-server/specification.rst index a9ab9bff66..17cffafdd4 100644 --- a/docs/server-server/specification.rst +++ b/docs/server-server/specification.rst @@ -155,7 +155,7 @@ Protocol URLs All these URLs are namespaced within a prefix of - /matrix/federation/v1/... + /_matrix/federation/v1/... For active pushing of messages representing live activity "as it happens": diff --git a/docs/specification.rst b/docs/specification.rst index d4a01a3fc2..3288aac019 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -35,8 +35,8 @@ namespaced to the home server which allocated the account and looks like:: @localpart:domain -The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user. - +The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user. They are +case-insensitive. A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes. It is typically responsible for multiple clients. "Federation" is the term used to describe the @@ -60,7 +60,8 @@ identified via a "Room ID", which look like:: There is exactly one room ID for each room. Whilst the room ID does contain a domain, it is simply for namespacing room IDs. The room does NOT reside on the -domain specified. Room IDs are not meant to be human readable. +domain specified. Room IDs are not meant to be human readable. They ARE +case-sensitive. The following diagram shows an ``m.room.message`` event being sent in the room ``!qporfwt:matrix.org``:: @@ -102,10 +103,10 @@ Each room can also have multiple "Room Aliases", which looks like:: A room alias "points" to a room ID. The room ID the alias is pointing to can be obtained by visiting the domain specified. Room aliases are designed to be human readable strings -which can be used to publicise rooms. Note that the mapping from a room alias to a -room ID is not fixed, and may change over time to point to a different room ID. For this -reason, Clients SHOULD resolve the room alias to a room ID once and then use that ID on -subsequent requests. +which can be used to publicise rooms. They are case-insensitive. Note that the mapping +from a room alias to a room ID is not fixed, and may change over time to point to a +different room ID. For this reason, Clients SHOULD resolve the room alias to a room ID +once and then use that ID on subsequent requests. :: @@ -214,24 +215,150 @@ In contrast, these are invalid requests:: "key": "This is a put but it is missing a txnId." } + + +- TODO: All strings everywhere are UTF-8 + + + Receiving live updates on a client ---------------------------------- -- C-S longpoll event stream -- Concept of start/end tokens. -- Mention /initialSync to get token. +Clients can receive new events by long-polling the home server. This will hold open the +HTTP connection for a short period of time waiting for new events, returning early if an +event occurs. This is called the "Event Stream". All events which the client is authorised +to view will appear in the event stream. When the stream is closed, an ``end`` token is +returned. This token can be used in the next request to continue where the client left off. +When the client first logs in, they will need to initially synchronise with their home +server. This is achieved via the ``/initialSync`` API. This API also returns an ``end`` +token which can be used with the event stream. Rooms ===== -- How are they created? PDU anchor point: "root of the tree". + +Creation +-------- +To create a room, a client has to use the ``/createRoom`` API. There are various options +which can be set when creating a room: + +``visibility`` + Type: + String + Optional: + Yes + Value: + Either ``public`` or ``private``. + Description: + A ``public`` visibility indicates that the room will be shown in the public room list. A + ``private`` visibility will hide the room from the public room list. Rooms default to + ``public`` visibility if this key is not included. + +``room_alias_name`` + Type: + String + Optional: + Yes + Value: + The room alias localpart. + Description: + If this is included, a room alias will be created and mapped to the newly created room. + The alias will belong on the same home server which created the room, e.g. + ``!qadnasoi:domain.com >>> #room_alias_name:domain.com`` + +Example:: + + { + "visibility": "public", + "room_alias_name": "the pub" + } + +- TODO: This creates a room creation event which serves as the root of the PDU graph for this room. + +Modifying aliases +----------------- - Adding / removing aliases. -- Invite/join dance -- State and non-state data (+extensibility) -TODO : Room permissions / config / power levels. +Permissions +----------- +- TODO : Room permissions / config / power levels. What they are. How do they work. Examples. + +Joining rooms +------------- +- What is joining? What permissions / access does it give you? How does this affect /initialSync? +- API to hit (``/join/$alias or id``). Explain how alias joining works (auto-resolving). See "Room events" for more info. +- What does the home server have to do? +- Rooms that DON'T need an invite to join. This follows through onto inviting users section. +- Outline invite join dance? -Messages -======== + +Inviting users +-------------- +- Can invite users to a room if the room config key TODO is set to TODO. Must have required power level. +- Outline invite join dance. What is it? Why is it required? How does it work? +- What does the home server have to do? + +The purpose of inviting users to a room is to notify them that the room exists +so they can choose to become a member of that room. Some rooms require that all +users who join a room are previously invited to it (an "invite-only" room). +Whether a given room is an "invite-only" room is determined by the room config +key ``TODO``. It can have one of the following values: + + - TODO Room config invite only value explanation + - TODO Room config free-to-join value explanation + +Only users who have a membership state of ``join`` in a room can invite new +users to said room. The person being invited must not be in the ``join`` state +in the room. The fully-qualified user ID must be specified when inviting a user, +as the user may reside on a different home server. To invite a user, send the +following request to ``/rooms/<room id>/invite``, which will manage the +entire invitation process:: + + { + "user_id": "<user id to invite>" + } + +Alternatively, the membership state for this user in this room can be modified +directly by sending the following request to +``/rooms/<room id>/state/m.room.member/<url encoded user id>``:: + + { + "membership": "invite" + } + +See the "Room events" section for more information on ``m.room.member``. + +- TODO: In what circumstances will this NOT be equivalent to ``/invite``? + +Leaving rooms +------------- +- API to hit (``$roomid/leave``). See "Room events" for more info. +- Must be joined to leave. How does this affect /initialSync? +- Not ever being in a room is NOT equivalent to have left it (due to membership: leave). +- Need to be re-invited if invite-only room. +- If no more HSes in room, can delete room? +- Is there a dance? + +Events in a room +---------------- +- Split into state and non-state data +- Explain what they are, semantics, give examples of clobbering / not, use cases (msgs vs room names). + Not too much detail on the actual event contents. +- API to hit. +- Extensibility provided by the API for custom events. Examples. +- How this hooks into ``initialSync``. +- See the "Room Events" section for actual spec on each type. + +Syncing a room +-------------- +- Single room initial sync. API to hit. Why it might be used (lazy loading) + +Getting grouped state events +---------------------------- +- ``/members`` and ``/messages`` and the events they return. +- ``/state`` and it returns ALL THE THINGS. + +Room Events +=========== This specification outlines several standard event types, all of which are prefixed with ``m.`` @@ -244,7 +371,8 @@ State messages - m.room.config - m.room.invite_join -What are they, when are they used, what do they contain, how should they be used +What are they, when are they used, what do they contain, how should they be used. +Link back to explanatory sections (e.g. invite/join/leave sections for m.room.member) Non-state messages ------------------ |