diff options
Diffstat (limited to 'docs/client-server')
| -rw-r--r-- | docs/client-server/swagger_matrix/api-docs | 4 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/events | 317 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/presence | 2 | ||||
| -rw-r--r-- | docs/client-server/swagger_matrix/rooms | 259 | ||||
| -rw-r--r-- | docs/client-server/urls.rst | 92 |
5 files changed, 105 insertions, 569 deletions
diff --git a/docs/client-server/swagger_matrix/api-docs b/docs/client-server/swagger_matrix/api-docs index d974dbb374..e52d4ee69d 100644 --- a/docs/client-server/swagger_matrix/api-docs +++ b/docs/client-server/swagger_matrix/api-docs @@ -21,6 +21,10 @@ { "path": "/presence", "description": "Presence operations" + }, + { + "path": "/events", + "description": "Event operations" } ], "authorizations": { diff --git a/docs/client-server/swagger_matrix/events b/docs/client-server/swagger_matrix/events index c9eb3f6ff7..e8b96861f5 100644 --- a/docs/client-server/swagger_matrix/events +++ b/docs/client-server/swagger_matrix/events @@ -1,208 +1,59 @@ { "apiVersion": "1.0.0", "swaggerVersion": "1.2", - "basePath": "http://petstore.swagger.wordnik.com/api", - "resourcePath": "/user", + "basePath": "http://localhost:8080/matrix/client/api/v1", + "resourcePath": "/events", "produces": [ "application/json" ], "apis": [ { - "path": "/user", - "operations": [ - { - "method": "POST", - "summary": "Create user", - "notes": "This can only be done by the logged in user.", - "type": "void", - "nickname": "createUser", - "authorizations": { - "oauth2": [ - { - "scope": "test:anything", - "description": "anything" - } - ] - }, - "parameters": [ - { - "name": "body", - "description": "Created user object", - "required": true, - "type": "User", - "paramType": "body" - } - ] - } - ] - }, - { - "path": "/user/logout", + "path": "/events", "operations": [ { "method": "GET", - "summary": "Logs out current logged in user session", - "notes": "", - "type": "void", - "nickname": "logoutUser", - "authorizations": {}, - "parameters": [] + "summary": "Listen on the event stream", + "notes": "This can only be done by the logged in user. This will block until an event is received, or until the timeout is reached.", + "type": "PaginationChunk", + "nickname": "get_event_stream" } - ] - }, - { - "path": "/user/createWithArray", - "operations": [ + ], + "parameters": [ { - "method": "POST", - "summary": "Creates list of users with given input array", - "notes": "", - "type": "void", - "nickname": "createUsersWithArrayInput", - "authorizations": { - "oauth2": [ - { - "scope": "test:anything", - "description": "anything" - } - ] - }, - "parameters": [ - { - "name": "body", - "description": "List of user object", - "required": true, - "type": "array", - "items": { - "$ref": "User" - }, - "paramType": "body" - } - ] + "name": "from", + "description": "The token to stream from.", + "required": false, + "type": "string", + "paramType": "query" + }, + { + "name": "timeout", + "description": "The maximum time in milliseconds to wait for an event.", + "required": false, + "type": "integer", + "paramType": "query" } - ] - }, - { - "path": "/user/createWithList", - "operations": [ + ], + "responseMessages": [ { - "method": "POST", - "summary": "Creates list of users with given list input", - "notes": "", - "type": "void", - "nickname": "createUsersWithListInput", - "authorizations": { - "oauth2": [ - { - "scope": "test:anything", - "description": "anything" - } - ] - }, - "parameters": [ - { - "name": "body", - "description": "List of user object", - "required": true, - "type": "array", - "items": { - "$ref": "User" - }, - "paramType": "body" - } - ] + "code": 400, + "message": "Bad pagination token." } ] }, { - "path": "/user/{username}", + "path": "/events/{eventId}", "operations": [ { - "method": "PUT", - "summary": "Updated user", - "notes": "This can only be done by the logged in user.", - "type": "void", - "nickname": "updateUser", - "authorizations": { - "oauth2": [ - { - "scope": "test:anything", - "description": "anything" - } - ] - }, - "parameters": [ - { - "name": "username", - "description": "name that need to be deleted", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "body", - "description": "Updated user object", - "required": true, - "type": "User", - "paramType": "body" - } - ], - "responseMessages": [ - { - "code": 400, - "message": "Invalid username supplied" - }, - { - "code": 404, - "message": "User not found" - } - ] - }, - { - "method": "DELETE", - "summary": "Delete user", - "notes": "This can only be done by the logged in user.", - "type": "void", - "nickname": "deleteUser", - "authorizations": { - "oauth2": [ - { - "scope": "test:anything", - "description": "anything" - } - ] - }, - "parameters": [ - { - "name": "username", - "description": "The name that needs to be deleted", - "required": true, - "type": "string", - "paramType": "path" - } - ], - "responseMessages": [ - { - "code": 400, - "message": "Invalid username supplied" - }, - { - "code": 404, - "message": "User not found" - } - ] - }, - { "method": "GET", - "summary": "Get user by user name", - "notes": "", - "type": "User", - "nickname": "getUserByName", - "authorizations": {}, + "summary": "Get information about a single event.", + "notes": "Get information about a single event.", + "type": "Event", + "nickname": "get_event", "parameters": [ { - "name": "username", - "description": "The name that needs to be fetched. Use user1 for testing.", + "name": "eventId", + "description": "The event ID to get.", "required": true, "type": "string", "paramType": "path" @@ -210,47 +61,8 @@ ], "responseMessages": [ { - "code": 400, - "message": "Invalid username supplied" - }, - { "code": 404, - "message": "User not found" - } - ] - } - ] - }, - { - "path": "/user/login", - "operations": [ - { - "method": "GET", - "summary": "Logs user into the system", - "notes": "", - "type": "string", - "nickname": "loginUser", - "authorizations": {}, - "parameters": [ - { - "name": "username", - "description": "The user name for login", - "required": true, - "type": "string", - "paramType": "query" - }, - { - "name": "password", - "description": "The password for login in clear text", - "required": true, - "type": "string", - "paramType": "query" - } - ], - "responseMessages": [ - { - "code": 400, - "message": "Invalid username and password combination" + "message": "Event not found." } ] } @@ -258,42 +70,43 @@ } ], "models": { - "User": { - "id": "User", + "PaginationChunk": { + "id": "PaginationChunk", "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "firstName": { - "type": "string" - }, - "username": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "email": { - "type": "string" + "start": { + "type": "string", + "description": "A token which correlates to the first value in \"chunk\" for paginating.", + "required": true }, - "password": { - "type": "string" + "end": { + "type": "string", + "description": "A token which correlates to the last value in \"chunk\" for paginating.", + "required": true }, - "phone": { - "type": "string" + "chunk": { + "type": "array", + "description": "An array of events.", + "required": true, + "items": { + "$ref": "Event" + } + } + } + }, + "Event": { + "id": "Event", + "properties": { + "event_id": { + "type": "string", + "description": "An ID which uniquely identifies this event.", + "required": true }, - "userStatus": { - "type": "integer", - "format": "int32", - "description": "User Status", - "enum": [ - "1-registered", - "2-active", - "3-closed" - ] + "room_id": { + "type": "string", + "description": "The room in which this event occurred.", + "required": true } } } } -} \ No newline at end of file +} diff --git a/docs/client-server/swagger_matrix/presence b/docs/client-server/swagger_matrix/presence index ee9deb12f0..1b4c7323aa 100644 --- a/docs/client-server/swagger_matrix/presence +++ b/docs/client-server/swagger_matrix/presence @@ -55,7 +55,7 @@ ] }, { - "path": "/presence_list/{userId}", + "path": "/presence/list/{userId}", "operations": [ { "method": "GET", diff --git a/docs/client-server/swagger_matrix/rooms b/docs/client-server/swagger_matrix/rooms index 47a8887240..7a2b5399a2 100644 --- a/docs/client-server/swagger_matrix/rooms +++ b/docs/client-server/swagger_matrix/rooms @@ -14,7 +14,7 @@ }, "apis": [ { - "path": "/rooms/{roomId}/messages/{userId}/{messageId}", + "path": "/rooms/{roomId}/send/m.room.message/{txnId}", "operations": [ { "method": "PUT", @@ -41,67 +41,18 @@ "paramType": "path" }, { - "name": "userId", - "description": "The fully qualified message sender's user ID.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "messageId", - "description": "A message ID which is unique for each room and user.", - "required": true, - "type": "string", - "paramType": "path" - } - ], - "responseMessages": [ - { - "code": 403, - "message": "Must send messages as yourself." - } - ] - }, - { - "method": "GET", - "summary": "Get a message from this room.", - "notes": "Get a message from this room.", - "type": "Message", - "nickname": "get_message", - "parameters": [ - { - "name": "roomId", - "description": "The room to send the message in.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "userId", - "description": "The fully qualified message sender's user ID.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "messageId", - "description": "A message ID which is unique for each room and user.", + "name": "txnId", + "description": "A client transaction ID to ensure idempotency.", "required": true, "type": "string", "paramType": "path" } - ], - "responseMessages": [ - { - "code": 404, - "message": "Message not found." - } ] } ] }, { - "path": "/rooms/{roomId}/topic", + "path": "/rooms/{roomId}/state/m.room.topic", "operations": [ { "method": "PUT", @@ -127,12 +78,6 @@ "type": "string", "paramType": "path" } - ], - "responseMessages": [ - { - "code": 403, - "message": "Must send messages as yourself." - } ] }, { @@ -160,7 +105,7 @@ ] }, { - "path": "/rooms/{roomId}/messages/{msgSenderId}/{messageId}/feedback/{senderId}/{feedbackType}", + "path": "/rooms/{roomId}/send/m.room.message.feedback/{txnId}", "operations": [ { "method": "PUT", @@ -187,105 +132,33 @@ "paramType": "path" }, { - "name": "msgSenderId", - "description": "The fully qualified message sender's user ID.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "messageId", - "description": "A message ID which is unique for each room and user.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "senderId", - "description": "The fully qualified feedback sender's user ID.", + "name": "txnId", + "description": "A client transaction ID to ensure idempotency.", "required": true, "type": "string", "paramType": "path" - }, - { - "name": "feedbackType", - "description": "The type of feedback being sent.", - "required": true, - "type": "string", - "paramType": "path", - "enum": [ - "d", - "r" - ] } ], "responseMessages": [ { - "code": 403, - "message": "Must send feedback as yourself." - }, - { "code": 400, "message": "Bad feedback type." } ] - }, - { - "method": "GET", - "summary": "Get feedback for a message.", - "notes": "Get feedback for a message.", - "type": "Feedback", - "nickname": "get_feedback", - "parameters": [ - { - "name": "roomId", - "description": "The room to send the message in.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "msgSenderId", - "description": "The fully qualified message sender's user ID.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "messageId", - "description": "A message ID which is unique for each room and user.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "senderId", - "description": "The fully qualified feedback sender's user ID.", - "required": true, - "type": "string", - "paramType": "path" - }, - { - "name": "feedbackType", - "description": "Enum: The type of feedback being sent.", - "required": true, - "type": "string", - "paramType": "path", - "enum": [ - "d", - "r" - ] - } - ], - "responseMessages": [ - { - "code": 404, - "message": "Feedback not found." - } - ] } ] }, + + + + + + + + + + + { "path": "/rooms/{roomId}/members/{userId}/state", "operations": [ @@ -412,22 +285,30 @@ } ] }, + + + + + + + + { - "path": "/join/{roomAlias}", + "path": "/join/{roomAliasOrId}", "operations": [ { "method": "PUT", - "summary": "Join a room via a room alias.", - "notes": "Join a room via a room alias.", + "summary": "Join a room via a room alias or room ID.", + "notes": "Join a room via a room alias or room ID.", "type": "RoomInfo", - "nickname": "join_room_via_alias", + "nickname": "join", "consumes": [ "application/json" ], "parameters": [ { - "name": "roomAlias", - "description": "The room alias to join.", + "name": "roomAliasOrId", + "description": "The room alias or room ID to join.", "required": true, "type": "string", "paramType": "path" @@ -443,7 +324,7 @@ ] }, { - "path": "/rooms", + "path": "/createRoom", "operations": [ { "method": "POST", @@ -477,7 +358,7 @@ ] }, { - "path": "/rooms/{roomId}/messages/list", + "path": "/rooms/{roomId}/messages", "operations": [ { "method": "GET", @@ -519,7 +400,7 @@ ] }, { - "path": "/rooms/{roomId}/members/list", + "path": "/rooms/{roomId}/members", "operations": [ { "method": "GET", @@ -732,76 +613,6 @@ "type": "Member" } } - }, - "Tag": { - "id": "Tag", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - } - }, - "Pet": { - "id": "Pet", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "unique identifier for the pet", - "minimum": "0.0", - "maximum": "100.0" - }, - "category": { - "$ref": "Category" - }, - "name": { - "type": "string" - }, - "photoUrls": { - "type": "array", - "items": { - "type": "string" - } - }, - "tags": { - "type": "array", - "items": { - "$ref": "Tag" - } - }, - "status": { - "type": "string", - "description": "pet status in the store", - "enum": [ - "available", - "pending", - "sold" - ] - } - } - }, - "Category": { - "id": "Category", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "pet": { - "$ref": "Pet" - } - } } } } diff --git a/docs/client-server/urls.rst b/docs/client-server/urls.rst deleted file mode 100644 index c0d2eaa80c..0000000000 --- a/docs/client-server/urls.rst +++ /dev/null @@ -1,92 +0,0 @@ -========================= -Client-Server URL Summary -========================= - -A brief overview of the URL scheme involved in the Synapse Client-Server API. - - -URLs -==== - -Fetch events: - GET /events - -Registering an account - POST /register - -Unregistering an account - POST /unregister - -Rooms ------ - -Creating a room by ID - PUT /rooms/$roomid - -Creating an anonymous room - POST /rooms - -Room topic - GET /rooms/$roomid/topic - PUT /rooms/$roomid/topic - -List rooms - GET /rooms/list - -Invite/Join/Leave - GET /rooms/$roomid/members/$userid/state - PUT /rooms/$roomid/members/$userid/state - DELETE /rooms/$roomid/members/$userid/state - -List members - GET /rooms/$roomid/members/list - -Sending/reading messages - PUT /rooms/$roomid/messages/$sender/$msgid - -Feedback - GET /rooms/$roomid/messages/$sender/$msgid/feedback/$feedbackuser/$feedback - PUT /rooms/$roomid/messages/$sender/$msgid/feedback/$feedbackuser/$feedback - -Paginating messages - GET /rooms/$roomid/messages/list - -Profiles --------- - -Display name - GET /profile/$userid/displayname - PUT /profile/$userid/displayname - -Avatar URL - GET /profile/$userid/avatar_url - PUT /profile/$userid/avatar_url - -Metadata - GET /profile/$userid/metadata - POST /profile/$userid/metadata - -Presence --------- - -My state or status message - GET /presence/$userid/status - PUT /presence/$userid/status - also 'GET' for fetching others - -TODO(paul): per-device idle time, device type; similar to above - -My presence list - GET /presence_list/$myuserid - POST /presence_list/$myuserid - body is JSON-encoded dict of keys: - invite: list of UserID strings to invite - drop: list of UserID strings to remove - TODO(paul): define other ops: accept, group management, ordering? - -Presence polling start/stop - POST /presence_list/$myuserid?op=start - POST /presence_list/$myuserid?op=stop - -Presence invite - POST /presence_list/$myuserid/invite/$targetuserid |