From 71095f4e6e0504fc51a1ca916650c6822129f401 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 27 Aug 2014 12:14:26 +0100 Subject: Updated swagger JSON: cleaned up unused entries. Converted most paths to the new format. --- docs/client-server/swagger_matrix/rooms | 259 +++++--------------------------- 1 file changed, 35 insertions(+), 224 deletions(-) (limited to 'docs/client-server/swagger_matrix/rooms') 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" - } - } } } } -- cgit 1.4.1 From abe2035d8518d334910024cbf20f0917781d317e Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 27 Aug 2014 15:41:19 +0100 Subject: api docs: Finished adding all C-S APIs. Added initialSync, publicRooms, membership changes (generic and RPCy) and directory paths. --- docs/client-server/swagger_matrix/api-docs | 4 + docs/client-server/swagger_matrix/directory | 83 ++++++++++++++ docs/client-server/swagger_matrix/events | 134 +++++++++++++++++++++++ docs/client-server/swagger_matrix/rooms | 163 +++++++++++++++++++--------- 4 files changed, 331 insertions(+), 53 deletions(-) create mode 100644 docs/client-server/swagger_matrix/directory (limited to 'docs/client-server/swagger_matrix/rooms') diff --git a/docs/client-server/swagger_matrix/api-docs b/docs/client-server/swagger_matrix/api-docs index e52d4ee69d..58462a9067 100644 --- a/docs/client-server/swagger_matrix/api-docs +++ b/docs/client-server/swagger_matrix/api-docs @@ -25,6 +25,10 @@ { "path": "/events", "description": "Event operations" + }, + { + "path": "/directory", + "description": "Directory operations" } ], "authorizations": { diff --git a/docs/client-server/swagger_matrix/directory b/docs/client-server/swagger_matrix/directory new file mode 100644 index 0000000000..3f3bef9c11 --- /dev/null +++ b/docs/client-server/swagger_matrix/directory @@ -0,0 +1,83 @@ +{ + "apiVersion": "1.0.0", + "swaggerVersion": "1.2", + "basePath": "http://localhost:8080/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.", + "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.", + "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" + } + ] + } + ] + } + ], + "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/docs/client-server/swagger_matrix/events b/docs/client-server/swagger_matrix/events index e8b96861f5..ca69d34db5 100644 --- a/docs/client-server/swagger_matrix/events +++ b/docs/client-server/swagger_matrix/events @@ -67,6 +67,38 @@ ] } ] + }, + { + "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": { @@ -107,6 +139,108 @@ "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/docs/client-server/swagger_matrix/rooms b/docs/client-server/swagger_matrix/rooms index 7a2b5399a2..1ead8b8c14 100644 --- a/docs/client-server/swagger_matrix/rooms +++ b/docs/client-server/swagger_matrix/rooms @@ -148,19 +148,108 @@ } ] }, - - - - - - - - - - - { - "path": "/rooms/{roomId}/members/{userId}/state", + "path": "/rooms/{roomId}/invite/{txnId}", + "operations": [ + { + "method": "PUT", + "summary": "Invite a user to this room.", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/invite", + "type": "void", + "nickname": "invite", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room which has this user.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "txnId", + "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", + "required": false, + "type": "string", + "paramType": "path" + }, + { + "name": "body", + "description": "The user to invite.", + "required": true, + "type": "InviteRequest", + "paramType": "body" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/join/{txnId}", + "operations": [ + { + "method": "PUT", + "summary": "Join this room.", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/join", + "type": "void", + "nickname": "join_room", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room to join.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "txnId", + "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", + "required": false, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/leave/{txnId}", + "operations": [ + { + "method": "PUT", + "summary": "Leave this room.", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/leave", + "type": "void", + "nickname": "leave", + "consumes": [ + "application/json" + ], + "parameters": [ + { + "name": "roomId", + "description": "The room to leave.", + "required": true, + "type": "string", + "paramType": "path" + }, + { + "name": "txnId", + "description": "A client transaction ID for this PUT to ensure idempotency. This can only be omitted if the HTTP method becomes a POST. ", + "required": false, + "type": "string", + "paramType": "path" + } + ] + } + ] + }, + { + "path": "/rooms/{roomId}/state/m.room.member/{userId}", "operations": [ { "method": "PUT", @@ -249,50 +338,9 @@ "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": [ @@ -613,6 +661,15 @@ "type": "Member" } } + }, + "InviteRequest": { + "id": "InviteRequest", + "properties": { + "user_id": { + "type": "string", + "description": "The fully-qualified user ID." + } + } } } } -- cgit 1.4.1 From e179ed1f60855d439031113bf52a0ff74c57df95 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 27 Aug 2014 16:16:40 +0100 Subject: Added generic state/non-state event sending to the API docs. --- docs/client-server/swagger_matrix/rooms | 131 ++++++++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 8 deletions(-) (limited to 'docs/client-server/swagger_matrix/rooms') diff --git a/docs/client-server/swagger_matrix/rooms b/docs/client-server/swagger_matrix/rooms index 1ead8b8c14..ce2843d6c9 100644 --- a/docs/client-server/swagger_matrix/rooms +++ b/docs/client-server/swagger_matrix/rooms @@ -13,14 +13,104 @@ "token": [] }, "apis": [ + { + "path": "/rooms/{roomId}/send/{eventType}/{txnId}", + "operations": [ + { + "method": "PUT", + "summary": "Send a generic non-state event to this room.", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/{eventType}", + "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" + }, + { + "name": "txnId", + "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", + "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/{txnId}", "operations": [ { "method": "PUT", "summary": "Send a message in this room.", - "notes": "Send a message in this room.", - "type": "void", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/m.room.message", + "type": "EventId", "nickname": "send_message", "consumes": [ "application/json" @@ -42,7 +132,7 @@ }, { "name": "txnId", - "description": "A client transaction ID to ensure idempotency.", + "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", "required": true, "type": "string", "paramType": "path" @@ -110,8 +200,8 @@ { "method": "PUT", "summary": "Send feedback to a message.", - "notes": "Send feedback to a message.", - "type": "void", + "notes": "This operation can also be done as a POST to /rooms/{roomId}/send/m.room.message.feedback", + "type": "EventId", "nickname": "send_feedback", "consumes": [ "application/json" @@ -133,7 +223,7 @@ }, { "name": "txnId", - "description": "A client transaction ID to ensure idempotency.", + "description": "A client transaction ID to ensure idempotency. This can only be omitted if the HTTP method becomes a POST.", "required": true, "type": "string", "paramType": "path" @@ -633,12 +723,17 @@ "properties": { "event_id": { "type": "string", - "description": "An ID which uniquely identifies this event.", + "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.", + "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 } }, @@ -646,6 +741,26 @@ "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": { -- cgit 1.4.1