summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/client-server/swagger_matrix/api-docs8
-rw-r--r--docs/client-server/swagger_matrix/directory83
-rw-r--r--docs/client-server/swagger_matrix/events419
-rw-r--r--docs/client-server/swagger_matrix/presence2
-rw-r--r--docs/client-server/swagger_matrix/rooms403
-rw-r--r--docs/client-server/urls.rst92
6 files changed, 468 insertions, 539 deletions
diff --git a/docs/client-server/swagger_matrix/api-docs b/docs/client-server/swagger_matrix/api-docs
index d974dbb374..58462a9067 100644
--- a/docs/client-server/swagger_matrix/api-docs
+++ b/docs/client-server/swagger_matrix/api-docs
@@ -21,6 +21,14 @@
     {
       "path": "/presence",
       "description": "Presence operations"
+    },
+    {
+      "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 c9eb3f6ff7..ca69d34db5 100644
--- a/docs/client-server/swagger_matrix/events
+++ b/docs/client-server/swagger_matrix/events
@@ -1,181 +1,59 @@
 {
   "apiVersion": "1.0.0",
   "swaggerVersion": "1.2",
-  "basePath": "http://petstore.swagger.wordnik.com/api",
-  "resourcePath": "/user",
+  "basePath": "http://localhost:8080/matrix/client/api/v1",
+  "resourcePath": "/events",
   "produces": [
     "application/json"
   ],
   "apis": [
     {
-      "path": "/user",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Create user",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "createUser",
-          "authorizations": {
-            "oauth2": [
-              {
-                "scope": "test:anything",
-                "description": "anything"
-              }
-            ]
-          },
-          "parameters": [
-            {
-              "name": "body",
-              "description": "Created user object",
-              "required": true,
-              "type": "User",
-              "paramType": "body"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/user/logout",
+      "path": "/events",
       "operations": [
         {
           "method": "GET",
-          "summary": "Logs out current logged in user session",
-          "notes": "",
-          "type": "void",
-          "nickname": "logoutUser",
-          "authorizations": {},
-          "parameters": []
+          "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"
         }
-      ]
-    },
-    {
-      "path": "/user/createWithArray",
-      "operations": [
+      ],
+      "parameters": [
         {
-          "method": "POST",
-          "summary": "Creates list of users with given input array",
-          "notes": "",
-          "type": "void",
-          "nickname": "createUsersWithArrayInput",
-          "authorizations": {
-            "oauth2": [
-              {
-                "scope": "test:anything",
-                "description": "anything"
-              }
-            ]
-          },
-          "parameters": [
-            {
-              "name": "body",
-              "description": "List of user object",
-              "required": true,
-              "type": "array",
-              "items": {
-                "$ref": "User"
-              },
-              "paramType": "body"
-            }
-          ]
+          "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"
         }
-      ]
-    },
-    {
-      "path": "/user/createWithList",
-      "operations": [
+      ],
+      "responseMessages": [
         {
-          "method": "POST",
-          "summary": "Creates list of users with given list input",
-          "notes": "",
-          "type": "void",
-          "nickname": "createUsersWithListInput",
-          "authorizations": {
-            "oauth2": [
-              {
-                "scope": "test:anything",
-                "description": "anything"
-              }
-            ]
-          },
-          "parameters": [
-            {
-              "name": "body",
-              "description": "List of user object",
-              "required": true,
-              "type": "array",
-              "items": {
-                "$ref": "User"
-              },
-              "paramType": "body"
-            }
-          ]
+          "code": 400,
+          "message": "Bad pagination token."
         }
       ]
     },
     {
-      "path": "/user/{username}",
+      "path": "/events/{eventId}",
       "operations": [
         {
-          "method": "PUT",
-          "summary": "Updated user",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "updateUser",
-          "authorizations": {
-            "oauth2": [
-              {
-                "scope": "test:anything",
-                "description": "anything"
-              }
-            ]
-          },
-          "parameters": [
-            {
-              "name": "username",
-              "description": "name that need to be deleted",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "Updated user object",
-              "required": true,
-              "type": "User",
-              "paramType": "body"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Invalid username supplied"
-            },
-            {
-              "code": 404,
-              "message": "User not found"
-            }
-          ]
-        },
-        {
-          "method": "DELETE",
-          "summary": "Delete user",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "deleteUser",
-          "authorizations": {
-            "oauth2": [
-              {
-                "scope": "test:anything",
-                "description": "anything"
-              }
-            ]
-          },
+          "method": "GET",
+          "summary": "Get information about a single event.",
+          "notes": "Get information about a single event.",
+          "type": "Event",
+          "nickname": "get_event",
           "parameters": [
             {
-              "name": "username",
-              "description": "The name that needs to be deleted",
+              "name": "eventId",
+              "description": "The event ID to get.",
               "required": true,
               "type": "string",
               "paramType": "path"
@@ -183,117 +61,186 @@
           ],
           "responseMessages": [
             {
-              "code": 400,
-              "message": "Invalid username supplied"
-            },
-            {
               "code": 404,
-              "message": "User not found"
+              "message": "Event not found."
             }
           ]
-        },
+        }
+      ]
+    },
+    {
+      "path": "/initialSync",
+      "operations": [
         {
           "method": "GET",
-          "summary": "Get user by user name",
-          "notes": "",
-          "type": "User",
-          "nickname": "getUserByName",
-          "authorizations": {},
+          "summary": "Get this user's current state.",
+          "notes": "Get this user's current state.",
+          "type": "InitialSyncResponse",
+          "nickname": "initial_sync",
           "parameters": [
             {
-              "name": "username",
-              "description": "The name that needs to be fetched. Use user1 for testing.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Invalid username supplied"
-            },
-            {
-              "code": 404,
-              "message": "User not found"
+              "name": "limit",
+              "description": "The maximum number of messages to return for each room.",
+              "type": "integer",
+              "paramType": "query",
+              "required": false
             }
           ]
         }
       ]
     },
     {
-      "path": "/user/login",
+      "path": "/publicRooms",
       "operations": [
         {
           "method": "GET",
-          "summary": "Logs user into the system",
-          "notes": "",
-          "type": "string",
-          "nickname": "loginUser",
-          "authorizations": {},
-          "parameters": [
-            {
-              "name": "username",
-              "description": "The user name for login",
-              "required": true,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "password",
-              "description": "The password for login in clear text",
-              "required": true,
-              "type": "string",
-              "paramType": "query"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Invalid username and password combination"
-            }
-          ]
+          "summary": "Get a list of publicly visible rooms.",
+          "type": "PublicRoomsPaginationChunk",
+          "nickname": "get_public_room_list"
         }
       ]
     }
   ],
   "models": {
-    "User": {
-      "id": "User",
+    "PaginationChunk": {
+      "id": "PaginationChunk",
       "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
+        "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
         },
-        "firstName": {
-          "type": "string"
+        "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
         },
-        "username": {
-          "type": "string"
+        "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
         },
-        "lastName": {
-          "type": "string"
+        "presence": {
+          "type": "array",
+          "description": "A list of presence events.",
+          "items": {
+            "$ref": "Event"
+          },
+          "required": false
         },
-        "email": {
-          "type": "string"
+        "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
         },
-        "password": {
-          "type": "string"
+        "room_id": {
+          "type": "string",
+          "description": "The ID of this room.",
+          "required": true
         },
-        "phone": {
-          "type": "string"
+        "messages": {
+          "type": "PaginationChunk",
+          "description": "The most recent messages for this room, governed by the limit parameter.",
+          "required": false
         },
-        "userStatus": {
-          "type": "integer",
-          "format": "int32",
-          "description": "User Status",
-          "enum": [
-            "1-registered",
-            "2-active",
-            "3-closed"
-          ]
+        "state": {
+          "type": "array",
+          "description": "A list of state events representing the current state of the room.",
+          "required": false,
+          "items": {
+            "$ref": "Event"
+          }
         }
       }
     }
   }
-}
\ No newline at end of file
+}
diff --git a/docs/client-server/swagger_matrix/presence b/docs/client-server/swagger_matrix/presence
index ee9deb12f0..1b4c7323aa 100644
--- a/docs/client-server/swagger_matrix/presence
+++ b/docs/client-server/swagger_matrix/presence
@@ -55,7 +55,7 @@
       ]
     },
     {
-      "path": "/presence_list/{userId}",
+      "path": "/presence/list/{userId}",
       "operations": [
         {
           "method": "GET",
diff --git a/docs/client-server/swagger_matrix/rooms b/docs/client-server/swagger_matrix/rooms
index 47a8887240..ce2843d6c9 100644
--- a/docs/client-server/swagger_matrix/rooms
+++ b/docs/client-server/swagger_matrix/rooms
@@ -14,23 +14,23 @@
   },
   "apis": [
     {
-      "path": "/rooms/{roomId}/messages/{userId}/{messageId}",
+      "path": "/rooms/{roomId}/send/{eventType}/{txnId}",
       "operations": [
         {
           "method": "PUT",
-          "summary": "Send a message in this room.",
-          "notes": "Send a message in this room.",
-          "type": "void",
-          "nickname": "send_message",
+          "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 message contents",
+              "description": "The event contents",
               "required": true,
-              "type": "Message",
+              "type": "EventContent",
               "paramType": "body"
             },
             {
@@ -41,35 +41,44 @@
               "paramType": "path"
             },
             {
-              "name": "userId",
-              "description": "The fully qualified message sender's user ID.",
+              "name": "eventType",
+              "description": "The type of event to send.",
               "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. This can only be omitted if the HTTP method becomes a POST.",
               "required": true,
               "type": "string",
               "paramType": "path"
             }
-          ],
-          "responseMessages": [
-            {
-              "code": 403,
-              "message": "Must send messages as yourself."
-            }
           ]
-        },
+        }
+      ]
+    },
+    {
+      "path": "/rooms/{roomId}/state/{eventType}/{stateKey}",
+      "operations": [
         {
-          "method": "GET",
-          "summary": "Get a message from this room.",
-          "notes": "Get a message from this room.",
-          "type": "Message",
-          "nickname": "get_message",
+          "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,
@@ -77,31 +86,63 @@
               "paramType": "path"
             },
             {
-              "name": "userId",
-              "description": "The fully qualified message sender's user ID.",
+              "name": "eventType",
+              "description": "The type of event to send.",
               "required": true,
               "type": "string",
               "paramType": "path"
             },
             {
-              "name": "messageId",
-              "description": "A message ID which is unique for each room and user.",
+              "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": "This operation can also be done as a POST to /rooms/{roomId}/send/m.room.message",
+          "type": "EventId",
+          "nickname": "send_message",
+          "consumes": [
+            "application/json"
           ],
-          "responseMessages": [
+          "parameters": [
             {
-              "code": 404,
-              "message": "Message not found."
+              "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. This can only be omitted if the HTTP method becomes a POST.",
+              "required": true,
+              "type": "string",
+              "paramType": "path"
             }
           ]
         }
       ]
     },
     {
-      "path": "/rooms/{roomId}/topic",
+      "path": "/rooms/{roomId}/state/m.room.topic",
       "operations": [
         {
           "method": "PUT",
@@ -127,12 +168,6 @@
               "type": "string",
               "paramType": "path"
             }
-          ],
-          "responseMessages": [
-            {
-              "code": 403,
-              "message": "Must send messages as yourself."
-            }
           ]
         },
         {
@@ -160,13 +195,13 @@
       ]
     },
     {
-      "path": "/rooms/{roomId}/messages/{msgSenderId}/{messageId}/feedback/{senderId}/{feedbackType}",
+      "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",
+          "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"
@@ -187,107 +222,124 @@
               "paramType": "path"
             },
             {
-              "name": "msgSenderId",
-              "description": "The fully qualified message sender's user ID.",
+              "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"
-            },
-            {
-              "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": "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."
             }
           ]
-        },
+        }
+      ]
+    },
+    {
+      "path": "/rooms/{roomId}/invite/{txnId}",
+      "operations": [
         {
-          "method": "GET",
-          "summary": "Get feedback for a message.",
-          "notes": "Get feedback for a message.",
-          "type": "Feedback",
-          "nickname": "get_feedback",
+          "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 to send the message in.",
+              "description": "The room which has this user.",
               "required": true,
               "type": "string",
               "paramType": "path"
             },
             {
-              "name": "msgSenderId",
-              "description": "The fully qualified message sender's user ID.",
-              "required": true,
+              "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": "messageId",
-              "description": "A message ID which is unique for each room and user.",
+              "name": "body",
+              "description": "The user to invite.",
               "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
+              "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": "senderId",
-              "description": "The fully qualified feedback sender's user ID.",
+              "name": "roomId",
+              "description": "The room to join.",
               "required": true,
               "type": "string",
               "paramType": "path"
             },
             {
-              "name": "feedbackType",
-              "description": "Enum: The type of feedback being sent.",
-              "required": true,
+              "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",
-              "enum": [
-                "d",
-                "r"
-              ]
+              "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"
           ],
-          "responseMessages": [
+          "parameters": [
             {
-              "code": 404,
-              "message": "Feedback not found."
+              "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}/members/{userId}/state",
+      "path": "/rooms/{roomId}/state/m.room.member/{userId}",
       "operations": [
         {
           "method": "PUT",
@@ -376,58 +428,25 @@
               "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/{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 +462,7 @@
       ]
     },
     {
-      "path": "/rooms",
+      "path": "/createRoom",
       "operations": [
         {
           "method": "POST",
@@ -477,7 +496,7 @@
       ]
     },
     {
-      "path": "/rooms/{roomId}/messages/list",
+      "path": "/rooms/{roomId}/messages",
       "operations": [
         {
           "method": "GET",
@@ -519,7 +538,7 @@
       ]
     },
     {
-      "path": "/rooms/{roomId}/members/list",
+      "path": "/rooms/{roomId}/members",
       "operations": [
         {
           "method": "GET",
@@ -704,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
         }
       },
@@ -717,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": {
@@ -733,73 +777,12 @@
         }
       }
     },
-    "Tag": {
-      "id": "Tag",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
-        },
-        "name": {
-          "type": "string"
-        }
-      }
-    },
-    "Pet": {
-      "id": "Pet",
-      "required": [
-        "id",
-        "name"
-      ],
+    "InviteRequest": {
+      "id": "InviteRequest",
       "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": {
+        "user_id": {
           "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"
+          "description": "The fully-qualified user ID."
         }
       }
     }
diff --git a/docs/client-server/urls.rst b/docs/client-server/urls.rst
deleted file mode 100644
index c0d2eaa80c..0000000000
--- a/docs/client-server/urls.rst
+++ /dev/null
@@ -1,92 +0,0 @@
-=========================
-Client-Server URL Summary
-=========================
-
-A brief overview of the URL scheme involved in the Synapse Client-Server API.
-
-
-URLs
-====
-
-Fetch events:
-  GET /events
-
-Registering an account
-  POST /register
-
-Unregistering an account
-  POST /unregister
-
-Rooms
------
-
-Creating a room by ID
-  PUT /rooms/$roomid
-
-Creating an anonymous room
-  POST /rooms
-
-Room topic
-  GET /rooms/$roomid/topic
-  PUT /rooms/$roomid/topic
-
-List rooms
-  GET /rooms/list
-
-Invite/Join/Leave
-  GET    /rooms/$roomid/members/$userid/state
-  PUT    /rooms/$roomid/members/$userid/state
-  DELETE /rooms/$roomid/members/$userid/state
-
-List members
-  GET  /rooms/$roomid/members/list
-
-Sending/reading messages
-  PUT /rooms/$roomid/messages/$sender/$msgid
-
-Feedback
-  GET /rooms/$roomid/messages/$sender/$msgid/feedback/$feedbackuser/$feedback
-  PUT /rooms/$roomid/messages/$sender/$msgid/feedback/$feedbackuser/$feedback
-
-Paginating messages
-  GET /rooms/$roomid/messages/list
-
-Profiles
---------
-
-Display name
-  GET /profile/$userid/displayname
-  PUT /profile/$userid/displayname
-
-Avatar URL
-  GET /profile/$userid/avatar_url
-  PUT /profile/$userid/avatar_url
-
-Metadata
-  GET  /profile/$userid/metadata
-  POST /profile/$userid/metadata
-
-Presence
---------
-
-My state or status message
-  GET /presence/$userid/status
-  PUT /presence/$userid/status
-    also 'GET' for fetching others
-
-TODO(paul): per-device idle time, device type; similar to above
-
-My presence list
-  GET  /presence_list/$myuserid
-  POST /presence_list/$myuserid
-    body is JSON-encoded dict of keys:
-      invite: list of UserID strings to invite
-      drop: list of UserID strings to remove
-      TODO(paul): define other ops: accept, group management, ordering?
-
-Presence polling start/stop
-  POST /presence_list/$myuserid?op=start
-  POST /presence_list/$myuserid?op=stop
-
-Presence invite
-  POST /presence_list/$myuserid/invite/$targetuserid