diff options
Diffstat (limited to 'docs/client-server/swagger_matrix/api-docs-rooms')
| -rw-r--r-- | docs/client-server/swagger_matrix/api-docs-rooms | 821 |
1 files changed, 821 insertions, 0 deletions
diff --git a/docs/client-server/swagger_matrix/api-docs-rooms b/docs/client-server/swagger_matrix/api-docs-rooms new file mode 100644 index 0000000000..7d3341f097 --- /dev/null +++ b/docs/client-server/swagger_matrix/api-docs-rooms @@ -0,0 +1,821 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8080/_matrix/client/api/v1", + "resourcePath": "/rooms", + "produces": [ + "application/json" + ], + "consumes": [ + "application/json" + ], + "authorizations": { + "token": [] + }, + "apis": [ + { + "path": "/rooms/{roomId}/send/{eventType}", + "operations": [ + { + "method": "POST", + "summary": "Send a generic non-state event to this room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "EventId", + "nickname": "send_non_state_event", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The event contents", + "required": true, + "type": "EventContent", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to send the message in.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "eventType", + "description": "The type of event to send.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/state/{eventType}/{stateKey}", + "operations": [ + { + "method": "PUT", + "summary": "Send a generic state event to this room.", + "notes": "The state key can be omitted, such that you can PUT to /rooms/{roomId}/state/{eventType}. The state key defaults to a 0 length string in this case.", + "type": "void", + "nickname": "send_state_event", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The event contents", + "required": true, + "type": "EventContent", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to send the message in.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "eventType", + "description": "The type of event to send.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "stateKey", + "description": "An identifier used to specify clobbering semantics. State events with the same (roomId, eventType, stateKey) will be replaced.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/send/m.room.message", + "operations": [ + { + "method": "POST", + "summary": "Send a message in this room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "EventId", + "nickname": "send_message", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The message contents", + "required": true, + "type": "Message", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to send the message in.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/state/m.room.topic", + "operations": [ + { + "method": "PUT", + "summary": "Set the topic for this room.", + "notes": "Set the topic for this room.", + "type": "void", + "nickname": "set_topic", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The topic contents", + "required": true, + "type": "Topic", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to set the topic in.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "GET", + "summary": "Get the topic for this room.", + "notes": "Get the topic for this room.", + "type": "Topic", + "nickname": "get_topic", + "parameters": [ + { + "name": "roomId", + "description": "The room to get topic in.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 404, + "message": "Topic not found." + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/send/m.room.message.feedback", + "operations": [ + { + "method": "POST", + "summary": "Send feedback to a message.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "EventId", + "nickname": "send_feedback", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The feedback contents", + "required": true, + "type": "Feedback", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to send the feedback in.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "Bad feedback type." + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/invite", + "operations": [ + { + "method": "POST", + "summary": "Invite a user to this room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "void", + "nickname": "invite", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room which has this user.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "body", + "description": "The user to invite.", + "required": true, + "type": "InviteRequest", + "paramType": "body" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/join", + "operations": [ + { + "method": "POST", + "summary": "Join this room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "void", + "nickname": "join_room", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room to join.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/leave", + "operations": [ + { + "method": "POST", + "summary": "Leave this room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}.", + "type": "void", + "nickname": "leave", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room to leave.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/state/m.room.member/{userId}", + "operations": [ + { + "method": "PUT", + "summary": "Change the membership state for a user in a room.", + "notes": "Change the membership state for a user in a room.", + "type": "void", + "nickname": "set_membership", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The new membership state", + "required": true, + "type": "Member", + "paramType": "body" + }, + { + "name": "userId", + "description": "The user whose membership is being changed.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "roomId", + "description": "The room which has this user.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "No membership key." + }, + { + "code": 400, + "message": "Bad membership value." + }, + { + "code": 403, + "message": "When inviting: You are not in the room." + }, + { + "code": 403, + "message": "When inviting: <target> is already in the room." + }, + { + "code": 403, + "message": "When joining: Cannot force another user to join." + }, + { + "code": 403, + "message": "When joining: You are not invited to this room." + } + ] + }, + { + "method": "GET", + "summary": "Get the membership state of a user in a room.", + "notes": "Get the membership state of a user in a room.", + "type": "Member", + "nickname": "get_membership", + "parameters": [ + { + "name": "userId", + "description": "The user whose membership state you want to get.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "roomId", + "description": "The room which has this user.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 404, + "message": "Member not found." + } + ] + } + ] + }, + { + "path": "/join/{roomAliasOrId}", + "operations": [ + { + "method": "PUT", + "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", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomAliasOrId", + "description": "The room alias or room ID to join.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "Bad room alias." + } + ] + } + ] + }, + { + "path": "/createRoom", + "operations": [ + { + "method": "POST", + "summary": "Create a room.", + "notes": "Create a room.", + "type": "RoomInfo", + "nickname": "create_room", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "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" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "Body must be JSON." + }, + { + "code": 400, + "message": "Room alias already taken." + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/messages", + "operations": [ + { + "method": "GET", + "summary": "Get a list of messages for this room.", + "notes": "Get a list of messages for this room.", + "type": "MessagePaginationChunk", + "nickname": "get_messages", + "parameters": [ + { + "name": "roomId", + "description": "The room to get messages in.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "from", + "description": "The token to start getting results from.", + "required": false, + "type": "string", + "paramType": "query" + }, + { + "name": "to", + "description": "The token to stop getting results at.", + "required": false, + "type": "string", + "paramType": "query" + }, + { + "name": "limit", + "description": "The maximum number of messages to return.", + "required": false, + "type": "integer", + "paramType": "query" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/members", + "operations": [ + { + "method": "GET", + "summary": "Get a list of members for this room.", + "notes": "Get a list of members for this room.", + "type": "MemberPaginationChunk", + "nickname": "get_members", + "parameters": [ + { + "name": "roomId", + "description": "The room to get a list of members from.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "from", + "description": "The token to start getting results from.", + "required": false, + "type": "string", + "paramType": "query" + }, + { + "name": "to", + "description": "The token to stop getting results at.", + "required": false, + "type": "string", + "paramType": "query" + }, + { + "name": "limit", + "description": "The maximum number of members to return.", + "required": false, + "type": "integer", + "paramType": "query" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/state", + "operations": [ + { + "method": "GET", + "summary": "Get a list of all the current state events for this room.", + "notes": "Get a list of all the current state events for this room.", + "type": "array", + "items": { + "$ref": "Event" + }, + "nickname": "get_state_events", + "parameters": [ + { + "name": "roomId", + "description": "The room to get a list of current state events from.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/initialSync", + "operations": [ + { + "method": "GET", + "summary": "Get all the current information for this room, including messages and state events.", + "notes": "Get all the current information for this room, including messages and state events.", + "type": "InitialSyncRoomData", + "nickname": "get_room_sync_data", + "parameters": [ + { + "name": "roomId", + "description": "The room to get information for.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + } + ], + "models": { + "Topic": { + "id": "Topic", + "properties": { + "topic": { + "type": "string", + "description": "The topic text" + } + } + }, + "Message": { + "id": "Message", + "properties": { + "msgtype": { + "type": "string", + "description": "The type of message being sent, e.g. \"m.text\"", + "required": true + }, + "_msgtype_defined_keys_": { + "description": "Additional keys as defined by the msgtype, e.g. \"body\"" + } + } + }, + "Feedback": { + "id": "Feedback", + "properties": { + } + }, + "Member": { + "id": "Member", + "properties": { + "membership": { + "type": "string", + "description": "Enum: The membership state of this member.", + "enum": [ + "invite", + "join", + "leave", + "knock" + ] + } + } + }, + "RoomInfo": { + "id": "RoomInfo", + "properties": { + "room_id": { + "type": "string", + "description": "The allocated room ID.", + "required": true + }, + "room_alias": { + "type": "string", + "description": "The alias for the room.", + "required": false + } + } + }, + "RoomConfig": { + "id": "RoomConfig", + "properties": { + "visibility": { + "type": "string", + "description": "Enum: The room visibility.", + "required": false, + "enum": [ + "public", + "private" + ] + }, + "room_alias_name": { + "type": "string", + "description": "The alias to give the new room.", + "required": false + } + } + }, + "PaginationRequest": { + "id": "PaginationRequest", + "properties": { + "from": { + "type": "string", + "description": "The token to start getting results from." + }, + "to": { + "type": "string", + "description": "The token to stop getting results at." + }, + "limit": { + "type": "integer", + "description": "The maximum number of entries to return." + } + } + }, + "PaginationChunk": { + "id": "PaginationChunk", + "properties": { + "start": { + "type": "string", + "description": "A token which correlates to the first value in \"chunk\" for paginating.", + "required": true + }, + "end": { + "type": "string", + "description": "A token which correlates to the last value in \"chunk\" for paginating.", + "required": true + } + }, + "subTypes": [ + "MessagePaginationChunk" + ] + }, + "MessagePaginationChunk": { + "id": "MessagePaginationChunk", + "properties": { + "chunk": { + "type": "array", + "description": "A list of message events.", + "items": { + "$ref": "MessageEvent" + }, + "required": true + } + } + }, + "MemberPaginationChunk": { + "id": "MemberPaginationChunk", + "properties": { + "chunk": { + "type": "array", + "description": "A list of member events.", + "items": { + "$ref": "MemberEvent" + }, + "required": true + } + } + }, + "Event": { + "id": "Event", + "properties": { + "event_id": { + "type": "string", + "description": "An ID which uniquely identifies this event. This is automatically set by the server.", + "required": true + }, + "room_id": { + "type": "string", + "description": "The room in which this event occurred. This is automatically set by the server.", + "required": true + }, + "type": { + "type": "string", + "description": "The event type.", + "required": true + } + }, + "subTypes": [ + "MessageEvent" + ] + }, + "EventId": { + "id": "EventId", + "properties": { + "event_id": { + "type": "string", + "description": "The allocated event ID for this event.", + "required": true + } + } + }, + "EventContent": { + "id": "EventContent", + "properties": { + "__event_content_keys__": { + "type": "string", + "description": "Event-specific content keys and values.", + "required": false + } + } + }, + "MessageEvent": { + "id": "MessageEvent", + "properties": { + "content": { + "type": "Message" + } + } + }, + "MemberEvent": { + "id": "MemberEvent", + "properties": { + "content": { + "type": "Member" + } + } + }, + "InviteRequest": { + "id": "InviteRequest", + "properties": { + "user_id": { + "type": "string", + "description": "The fully-qualified user ID." + } + } + }, + "InitialSyncRoomData": { + "id": "InitialSyncRoomData", + "properties": { + "membership": { + "type": "string", + "description": "This user's membership state in this room.", + "required": true + }, + "room_id": { + "type": "string", + "description": "The ID of this room.", + "required": true + }, + "messages": { + "type": "MessagePaginationChunk", + "description": "The most recent messages for this room, governed by the limit parameter.", + "required": false + }, + "state": { + "type": "array", + "description": "A list of state events representing the current state of the room.", + "required": false, + "items": { + "$ref": "Event" + } + } + } + } + } +} |