forked from MirrorHub/synapse
618 lines
16 KiB
Text
618 lines
16 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/m.room.message/{txnId}",
|
|
"operations": [
|
|
{
|
|
"method": "PUT",
|
|
"summary": "Send a message in this room.",
|
|
"notes": "Send a message in this room.",
|
|
"type": "void",
|
|
"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"
|
|
},
|
|
{
|
|
"name": "txnId",
|
|
"description": "A client transaction ID to ensure idempotency.",
|
|
"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/{txnId}",
|
|
"operations": [
|
|
{
|
|
"method": "PUT",
|
|
"summary": "Send feedback to a message.",
|
|
"notes": "Send feedback to a message.",
|
|
"type": "void",
|
|
"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"
|
|
},
|
|
{
|
|
"name": "txnId",
|
|
"description": "A client transaction ID to ensure idempotency.",
|
|
"required": true,
|
|
"type": "string",
|
|
"paramType": "path"
|
|
}
|
|
],
|
|
"responseMessages": [
|
|
{
|
|
"code": 400,
|
|
"message": "Bad feedback type."
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{
|
|
"path": "/rooms/{roomId}/members/{userId}/state",
|
|
"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."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"method": "DELETE",
|
|
"summary": "Leave a room.",
|
|
"notes": "Leave a room.",
|
|
"type": "void",
|
|
"nickname": "remove_membership",
|
|
"parameters": [
|
|
{
|
|
"name": "userId",
|
|
"description": "The user who is leaving.",
|
|
"required": true,
|
|
"type": "string",
|
|
"paramType": "path"
|
|
},
|
|
{
|
|
"name": "roomId",
|
|
"description": "The room which has this user.",
|
|
"required": true,
|
|
"type": "string",
|
|
"paramType": "path"
|
|
}
|
|
],
|
|
"responseMessages": [
|
|
{
|
|
"code": 403,
|
|
"message": "You are not in the room."
|
|
},
|
|
{
|
|
"code": 403,
|
|
"message": "Cannot force another user to leave."
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{
|
|
"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.",
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"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.",
|
|
"required": true
|
|
},
|
|
"room_id": {
|
|
"type": "string",
|
|
"description": "The room in which this event occurred.",
|
|
"required": true
|
|
}
|
|
},
|
|
"subTypes": [
|
|
"MessageEvent"
|
|
]
|
|
},
|
|
"MessageEvent": {
|
|
"id": "MessageEvent",
|
|
"properties": {
|
|
"content": {
|
|
"type": "Message"
|
|
}
|
|
}
|
|
},
|
|
"MemberEvent": {
|
|
"id": "MemberEvent",
|
|
"properties": {
|
|
"content": {
|
|
"type": "Member"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|