forked from MirrorHub/synapse
821 lines
22 KiB
Text
821 lines
22 KiB
Text
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|