From 8e60c08bf006589a9c3ee8ace11b2e7ce2e4f547 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Thu, 9 Oct 2014 20:42:38 +0200 Subject: [PATCH] move swagger JSON from synapse project to matrix-doc project --- swagger/client-server/api-docs | 46 + swagger/client-server/api-docs-directory | 101 ++ swagger/client-server/api-docs-events | 247 +++++ swagger/client-server/api-docs-login | 120 +++ swagger/client-server/api-docs-presence | 164 ++++ swagger/client-server/api-docs-profile | 122 +++ swagger/client-server/api-docs-registration | 120 +++ swagger/client-server/api-docs-rooms | 977 ++++++++++++++++++++ 8 files changed, 1897 insertions(+) create mode 100644 swagger/client-server/api-docs create mode 100644 swagger/client-server/api-docs-directory create mode 100644 swagger/client-server/api-docs-events create mode 100644 swagger/client-server/api-docs-login create mode 100644 swagger/client-server/api-docs-presence create mode 100644 swagger/client-server/api-docs-profile create mode 100644 swagger/client-server/api-docs-registration create mode 100644 swagger/client-server/api-docs-rooms diff --git a/swagger/client-server/api-docs b/swagger/client-server/api-docs new file mode 100644 index 00000000..a80b3bb3 --- /dev/null +++ b/swagger/client-server/api-docs @@ -0,0 +1,46 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "apis": [ + { + "path": "-login", + "description": "Login operations" + }, + { + "path": "-registration", + "description": "Registration operations" + }, + { + "path": "-rooms", + "description": "Room operations" + }, + { + "path": "-profile", + "description": "Profile operations" + }, + { + "path": "-presence", + "description": "Presence operations" + }, + { + "path": "-events", + "description": "Event operations" + }, + { + "path": "-directory", + "description": "Directory operations" + } + ], + "authorizations": { + "token": { + "scopes": [] + } + }, + "info": { + "title": "Matrix Client-Server API Reference", + "description": "This contains the client-server API for the reference implementation of the home server", + "termsOfServiceUrl": "http://matrix.org", + "license": "Apache 2.0", + "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html" + } +} diff --git a/swagger/client-server/api-docs-directory b/swagger/client-server/api-docs-directory new file mode 100644 index 00000000..5dda5806 --- /dev/null +++ b/swagger/client-server/api-docs-directory @@ -0,0 +1,101 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "resourcePath": "/directory", + "produces": [ + "application/json" + ], + "apis": [ + { + "path": "/directory/room/{roomAlias}", + "operations": [ + { + "method": "GET", + "summary": "Get the room ID corresponding to this room alias.", + "notes": "Volatile: This API is likely to change.", + "type": "DirectoryResponse", + "nickname": "get_room_id_for_alias", + "parameters": [ + { + "name": "roomAlias", + "description": "The room alias.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "PUT", + "summary": "Create a new mapping from room alias to room ID.", + "notes": "Volatile: This API is likely to change.", + "type": "void", + "nickname": "add_room_alias", + "parameters": [ + { + "name": "roomAlias", + "description": "The room alias to set.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "body", + "description": "The room ID to set.", + "required": true, + "type": "RoomAliasRequest", + "paramType": "body" + } + ] + }, + { + "method": "DELETE", + "summary": "Removes a mapping of room alias to room ID.", + "notes": "Only privileged users can perform this action.", + "type": "void", + "nickname": "remove_room_alias", + "parameters": [ + { + "name": "roomAlias", + "description": "The room alias to remove.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + } + ], + "models": { + "DirectoryResponse": { + "id": "DirectoryResponse", + "properties": { + "room_id": { + "type": "string", + "description": "The fully-qualified room ID.", + "required": true + }, + "servers": { + "type": "array", + "items": { + "$ref": "string" + }, + "description": "A list of servers that know about this room.", + "required": true + } + } + }, + "RoomAliasRequest": { + "id": "RoomAliasRequest", + "properties": { + "room_id": { + "type": "string", + "description": "The room ID to map the alias to.", + "required": true + } + } + } + } +} diff --git a/swagger/client-server/api-docs-events b/swagger/client-server/api-docs-events new file mode 100644 index 00000000..1bdb9b03 --- /dev/null +++ b/swagger/client-server/api-docs-events @@ -0,0 +1,247 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "resourcePath": "/events", + "produces": [ + "application/json" + ], + "apis": [ + { + "path": "/events", + "operations": [ + { + "method": "GET", + "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", + "parameters": [ + { + "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" + } + ] + } + ], + + "responseMessages": [ + { + "code": 400, + "message": "Bad pagination token." + } + ] + }, + { + "path": "/events/{eventId}", + "operations": [ + { + "method": "GET", + "summary": "Get information about a single event.", + "notes": "Get information about a single event.", + "type": "Event", + "nickname": "get_event", + "parameters": [ + { + "name": "eventId", + "description": "The event ID to get.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 404, + "message": "Event not found." + } + ] + } + ] + }, + { + "path": "/initialSync", + "operations": [ + { + "method": "GET", + "summary": "Get this user's current state.", + "notes": "Get this user's current state.", + "type": "InitialSyncResponse", + "nickname": "initial_sync", + "parameters": [ + { + "name": "limit", + "description": "The maximum number of messages to return for each room.", + "type": "integer", + "paramType": "query", + "required": false + } + ] + } + ] + }, + { + "path": "/publicRooms", + "operations": [ + { + "method": "GET", + "summary": "Get a list of publicly visible rooms.", + "type": "PublicRoomsPaginationChunk", + "nickname": "get_public_room_list" + } + ] + } + ], + "models": { + "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 + }, + "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 + }, + "room_id": { + "type": "string", + "description": "The room in which this event occurred.", + "required": true + } + } + }, + "PublicRoomInfo": { + "id": "PublicRoomInfo", + "properties": { + "aliases": { + "type": "array", + "description": "A list of room aliases for this room.", + "items": { + "$ref": "string" + } + }, + "name": { + "type": "string", + "description": "The name of the room, as given by the m.room.name state event." + }, + "room_id": { + "type": "string", + "description": "The room ID for this public room.", + "required": true + }, + "topic": { + "type": "string", + "description": "The topic of this room, as given by the m.room.topic state event." + } + } + }, + "PublicRoomsPaginationChunk": { + "id": "PublicRoomsPaginationChunk", + "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 + }, + "chunk": { + "type": "array", + "description": "A list of public room data.", + "required": true, + "items": { + "$ref": "PublicRoomInfo" + } + } + } + }, + "InitialSyncResponse": { + "id": "InitialSyncResponse", + "properties": { + "end": { + "type": "string", + "description": "A streaming token which can be used with /events to continue from this snapshot of data.", + "required": true + }, + "presence": { + "type": "array", + "description": "A list of presence events.", + "items": { + "$ref": "Event" + }, + "required": false + }, + "rooms": { + "type": "array", + "description": "A list of initial sync room data.", + "required": false, + "items": { + "$ref": "InitialSyncRoomData" + } + } + } + }, + "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": "PaginationChunk", + "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" + } + } + } + } + } +} diff --git a/swagger/client-server/api-docs-login b/swagger/client-server/api-docs-login new file mode 100644 index 00000000..d6f8d84f --- /dev/null +++ b/swagger/client-server/api-docs-login @@ -0,0 +1,120 @@ +{ + "apiVersion": "1.0.0", + "apis": [ + { + "operations": [ + { + "method": "GET", + "nickname": "get_login_info", + "notes": "All login stages MUST be mentioned if there is >1 login type.", + "summary": "Get the login mechanism to use when logging in.", + "type": "LoginFlows" + }, + { + "method": "POST", + "nickname": "submit_login", + "notes": "If this is part of a multi-stage login, there MUST be a 'session' key.", + "parameters": [ + { + "description": "A login submission", + "name": "body", + "paramType": "body", + "required": true, + "type": "LoginSubmission" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "Bad login type" + }, + { + "code": 400, + "message": "Missing JSON keys" + } + ], + "summary": "Submit a login action.", + "type": "LoginResult" + } + ], + "path": "/login" + } + ], + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "consumes": [ + "application/json" + ], + "models": { + "LoginFlows": { + "id": "LoginFlows", + "properties": { + "flows": { + "description": "A list of valid login flows.", + "type": "array", + "items": { + "$ref": "LoginInfo" + } + } + } + }, + "LoginInfo": { + "id": "LoginInfo", + "properties": { + "stages": { + "description": "Multi-stage login only: An array of all the login types required to login.", + "items": { + "$ref": "string" + }, + "type": "array" + }, + "type": { + "description": "The login type that must be used when logging in.", + "type": "string" + } + } + }, + "LoginResult": { + "id": "LoginResult", + "properties": { + "access_token": { + "description": "The access token for this user's login if this is the final stage of the login process.", + "type": "string" + }, + "user_id": { + "description": "The user's fully-qualified user ID.", + "type": "string" + }, + "next": { + "description": "Multi-stage login only: The next login type to submit.", + "type": "string" + }, + "session": { + "description": "Multi-stage login only: The session token to send when submitting the next login type.", + "type": "string" + } + } + }, + "LoginSubmission": { + "id": "LoginSubmission", + "properties": { + "type": { + "description": "The type of login being submitted.", + "type": "string" + }, + "session": { + "description": "Multi-stage login only: The session token from an earlier login stage.", + "type": "string" + }, + "_login_type_defined_keys_": { + "description": "Keys as defined by the specified login type, e.g. \"user\", \"password\"" + } + } + } + }, + "produces": [ + "application/json" + ], + "resourcePath": "/login", + "swaggerVersion": "1.2" +} + diff --git a/swagger/client-server/api-docs-presence b/swagger/client-server/api-docs-presence new file mode 100644 index 00000000..6b224460 --- /dev/null +++ b/swagger/client-server/api-docs-presence @@ -0,0 +1,164 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "resourcePath": "/presence", + "produces": [ + "application/json" + ], + "consumes": [ + "application/json" + ], + "apis": [ + { + "path": "/presence/{userId}/status", + "operations": [ + { + "method": "PUT", + "summary": "Update this user's presence state.", + "notes": "This can only be done by the logged in user.", + "type": "void", + "nickname": "update_presence", + "parameters": [ + { + "name": "body", + "description": "The new presence state", + "required": true, + "type": "PresenceUpdate", + "paramType": "body" + }, + { + "name": "userId", + "description": "The user whose presence to set.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "GET", + "summary": "Get this user's presence state.", + "notes": "Get this user's presence state.", + "type": "PresenceUpdate", + "nickname": "get_presence", + "parameters": [ + { + "name": "userId", + "description": "The user whose presence to get.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/presence/list/{userId}", + "operations": [ + { + "method": "GET", + "summary": "Retrieve a list of presences for all of this user's friends.", + "notes": "", + "type": "array", + "items": { + "$ref": "Presence" + }, + "nickname": "get_presence_list", + "parameters": [ + { + "name": "userId", + "description": "The user whose presence list to get.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "POST", + "summary": "Add or remove users from this presence list.", + "notes": "Add or remove users from this presence list.", + "type": "void", + "nickname": "modify_presence_list", + "parameters": [ + { + "name": "userId", + "description": "The user whose presence list is being modified.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "body", + "description": "The modifications to make to this presence list.", + "required": true, + "type": "PresenceListModifications", + "paramType": "body" + } + ] + } + ] + } + ], + "models": { + "PresenceUpdate": { + "id": "PresenceUpdate", + "properties": { + "presence": { + "type": "string", + "description": "Enum: The presence state.", + "enum": [ + "offline", + "unavailable", + "online", + "free_for_chat" + ] + }, + "status_msg": { + "type": "string", + "description": "The user-defined message associated with this presence state." + } + }, + "subTypes": [ + "Presence" + ] + }, + "Presence": { + "id": "Presence", + "properties": { + "last_active_ago": { + "type": "integer", + "format": "int64", + "description": "The last time this user performed an action on their home server." + }, + "user_id": { + "type": "string", + "description": "The fully qualified user ID" + } + } + }, + "PresenceListModifications": { + "id": "PresenceListModifications", + "properties": { + "invite": { + "type": "array", + "description": "A list of user IDs to add to the list.", + "items": { + "type": "string", + "description": "A fully qualified user ID." + } + }, + "drop": { + "type": "array", + "description": "A list of user IDs to remove from the list.", + "items": { + "type": "string", + "description": "A fully qualified user ID." + } + } + } + } + } +} diff --git a/swagger/client-server/api-docs-profile b/swagger/client-server/api-docs-profile new file mode 100644 index 00000000..d2fccaa6 --- /dev/null +++ b/swagger/client-server/api-docs-profile @@ -0,0 +1,122 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "resourcePath": "/profile", + "produces": [ + "application/json" + ], + "consumes": [ + "application/json" + ], + "apis": [ + { + "path": "/profile/{userId}/displayname", + "operations": [ + { + "method": "PUT", + "summary": "Set a display name.", + "notes": "This can only be done by the logged in user.", + "type": "void", + "nickname": "set_display_name", + "parameters": [ + { + "name": "body", + "description": "The new display name for this user.", + "required": true, + "type": "DisplayName", + "paramType": "body" + }, + { + "name": "userId", + "description": "The user whose display name to set.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "GET", + "summary": "Get a display name.", + "notes": "This can be done by anyone.", + "type": "DisplayName", + "nickname": "get_display_name", + "parameters": [ + { + "name": "userId", + "description": "The user whose display name to get.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/profile/{userId}/avatar_url", + "operations": [ + { + "method": "PUT", + "summary": "Set an avatar URL.", + "notes": "This can only be done by the logged in user.", + "type": "void", + "nickname": "set_avatar_url", + "parameters": [ + { + "name": "body", + "description": "The new avatar url for this user.", + "required": true, + "type": "AvatarUrl", + "paramType": "body" + }, + { + "name": "userId", + "description": "The user whose avatar url to set.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "GET", + "summary": "Get an avatar url.", + "notes": "This can be done by anyone.", + "type": "AvatarUrl", + "nickname": "get_avatar_url", + "parameters": [ + { + "name": "userId", + "description": "The user whose avatar url to get.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + } + ] + } + ], + "models": { + "DisplayName": { + "id": "DisplayName", + "properties": { + "displayname": { + "type": "string", + "description": "The textual display name" + } + } + }, + "AvatarUrl": { + "id": "AvatarUrl", + "properties": { + "avatar_url": { + "type": "string", + "description": "A url to an image representing an avatar." + } + } + } + } +} diff --git a/swagger/client-server/api-docs-registration b/swagger/client-server/api-docs-registration new file mode 100644 index 00000000..11c170c3 --- /dev/null +++ b/swagger/client-server/api-docs-registration @@ -0,0 +1,120 @@ +{ + "apiVersion": "1.0.0", + "apis": [ + { + "operations": [ + { + "method": "GET", + "nickname": "get_registration_info", + "notes": "All login stages MUST be mentioned if there is >1 login type.", + "summary": "Get the login mechanism to use when registering.", + "type": "RegistrationFlows" + }, + { + "method": "POST", + "nickname": "submit_registration", + "notes": "If this is part of a multi-stage registration, there MUST be a 'session' key.", + "parameters": [ + { + "description": "A registration submission", + "name": "body", + "paramType": "body", + "required": true, + "type": "RegistrationSubmission" + } + ], + "responseMessages": [ + { + "code": 400, + "message": "Bad login type" + }, + { + "code": 400, + "message": "Missing JSON keys" + } + ], + "summary": "Submit a registration action.", + "type": "RegistrationResult" + } + ], + "path": "/register" + } + ], + "basePath": "http://localhost:8008/_matrix/client/api/v1", + "consumes": [ + "application/json" + ], + "models": { + "RegistrationFlows": { + "id": "RegistrationFlows", + "properties": { + "flows": { + "description": "A list of valid registration flows.", + "type": "array", + "items": { + "$ref": "RegistrationInfo" + } + } + } + }, + "RegistrationInfo": { + "id": "RegistrationInfo", + "properties": { + "stages": { + "description": "Multi-stage registration only: An array of all the login types required to registration.", + "items": { + "$ref": "string" + }, + "type": "array" + }, + "type": { + "description": "The first login type that must be used when logging in.", + "type": "string" + } + } + }, + "RegistrationResult": { + "id": "RegistrationResult", + "properties": { + "access_token": { + "description": "The access token for this user's registration if this is the final stage of the registration process.", + "type": "string" + }, + "user_id": { + "description": "The user's fully-qualified user ID.", + "type": "string" + }, + "next": { + "description": "Multi-stage registration only: The next registration type to submit.", + "type": "string" + }, + "session": { + "description": "Multi-stage registration only: The session token to send when submitting the next registration type.", + "type": "string" + } + } + }, + "RegistrationSubmission": { + "id": "RegistrationSubmission", + "properties": { + "type": { + "description": "The type of registration being submitted.", + "type": "string" + }, + "session": { + "description": "Multi-stage registration only: The session token from an earlier registration stage.", + "type": "string" + }, + "_registration_type_defined_keys_": { + "description": "Keys as defined by the specified registration type, e.g. \"user\", \"password\"" + } + } + } + }, + "produces": [ + "application/json" + ], + "resourcePath": "/register", + "swaggerVersion": "1.2" +} + diff --git a/swagger/client-server/api-docs-rooms b/swagger/client-server/api-docs-rooms new file mode 100644 index 00000000..b941e581 --- /dev/null +++ b/swagger/client-server/api-docs-rooms @@ -0,0 +1,977 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8008/_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}/state/m.room.name", + "operations": [ + { + "method": "PUT", + "summary": "Set the name of this room.", + "notes": "Set the name of this room.", + "type": "void", + "nickname": "set_room_name", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "description": "The name contents", + "required": true, + "type": "RoomName", + "paramType": "body" + }, + { + "name": "roomId", + "description": "The room to set the name of.", + "required": true, + "type": "string", + "paramType": "path" + } + ] + }, + { + "method": "GET", + "summary": "Get the room's name.", + "notes": "", + "type": "RoomName", + "nickname": "get_room_name", + "parameters": [ + { + "name": "roomId", + "description": "The room to get the name of.", + "required": true, + "type": "string", + "paramType": "path" + } + ], + "responseMessages": [ + { + "code": 404, + "message": "Name 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" + }, + { + "name": "body", + "required": true, + "type": "JoinRequest", + "paramType": "body" + } + ] + } + ] + }, + { + "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" + }, + { + "name": "body", + "required": true, + "type": "LeaveRequest", + "paramType": "body" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/ban", + "operations": [ + { + "method": "POST", + "summary": "Ban a user in the room.", + "notes": "This operation can also be done as a PUT by suffixing /{txnId}. The caller must have the required power level to do this operation.", + "type": "void", + "nickname": "ban", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room which has the user to ban.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "body", + "description": "The user to ban.", + "required": true, + "type": "BanRequest", + "paramType": "body" + } + ] + } + ] + }, + { + "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: 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": "POST", + "summary": "Join a room via a room alias or room ID.", + "notes": "Join a room via a room alias or room ID.", + "type": "JoinRoomInfo", + "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": "This is equivalent to the events returned under the 'state' key for this room in /initialSync.", + "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": "NOT YET IMPLEMENTED.", + "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" + } + } + }, + "RoomName": { + "id": "RoomName", + "properties": { + "name": { + "type": "string", + "description": "The human-readable name for the room. Can contain spaces." + } + } + }, + "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": { + "target_event_id": { + "type": "string", + "description": "The event ID being acknowledged.", + "required": true + }, + "type": { + "type": "string", + "description": "The type of feedback. Either 'delivered' or 'read'.", + "required": true + } + } + }, + "Member": { + "id": "Member", + "properties": { + "membership": { + "type": "string", + "description": "Enum: The membership state of this member.", + "enum": [ + "invite", + "join", + "leave", + "ban" + ] + } + } + }, + "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 + } + } + }, + "JoinRoomInfo": { + "id": "JoinRoomInfo", + "properties": { + "room_id": { + "type": "string", + "description": "The room ID joined, if joined via a room alias only.", + "required": true + } + } + }, + "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 + }, + "name": { + "type": "string", + "description": "Sets the name of the room. Send a m.room.name event after creating the room with the 'name' key specified.", + "required": false + }, + "topic": { + "type": "string", + "description": "Sets the topic for the room. Send a m.room.topic event after creating the room with the 'topic' key specified.", + "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." + } + } + }, + "JoinRequest": { + "id": "JoinRequest", + "properties": {} + }, + "LeaveRequest": { + "id": "LeaveRequest", + "properties": {} + }, + "BanRequest": { + "id": "BanRequest", + "properties": { + "user_id": { + "type": "string", + "description": "The fully-qualified user ID." + }, + "reason": { + "type": "string", + "description": "The reason for the ban." + } + } + }, + "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" + } + } + } + } + } +}