From 8824c2178879475e053cf9712ef2d6221527434b Mon Sep 17 00:00:00 2001
From: Tulir Asokan <tulir@maunium.net>
Date: Sat, 8 Dec 2018 19:47:40 +0200
Subject: [PATCH] Add spec for Matrix API proxy

---
 maubot/management/api/spec.md   | 14 +++++++++++-
 maubot/management/api/spec.yaml | 39 ---------------------------------
 2 files changed, 13 insertions(+), 40 deletions(-)

diff --git a/maubot/management/api/spec.md b/maubot/management/api/spec.md
index b487818..2e2b399 100644
--- a/maubot/management/api/spec.md
+++ b/maubot/management/api/spec.md
@@ -3,6 +3,18 @@ Most of the API is simple HTTP+JSON and has OpenAPI documentation (see
 [spec.yaml](spec.yaml), [rendered](https://maubot.xyz/spec/)). However,
 some parts of the API aren't documented in the OpenAPI document.
 
+## Matrix API proxy
+The full Matrix API can be accessed for each client with a request to
+`/_matrix/maubot/v1/proxy/<user>/<path>`. `<user>` is the Matrix user
+ID of the user to access the API as and `<path>` is the whole API
+path to access (e.g. `/_matrix/client/r0/whoami`).
+
+The body, headers, query parameters, etc are sent to the Matrix server
+as-is, with a few exceptions:
+* The `Authorization` header will be replaced with the access token
+  for the Matrix user from the maubot database.
+* The `access_token` query parameter will be removed.
+
 ## Log viewing
 1. Open websocket to `/_matrix/maubot/v1/logs`.
 2. Send authentication token as a plain string.
@@ -22,7 +34,7 @@ Log entries will always have:
 Log entries should also always have:
 * `levelname` - The log level (e.g. `DEBUG` or `ERROR`).
 * `levelno`   - The integer log level.
-* `name`      - The name of the logger. Possible values:
+* `name`      - The name of the logger. Common values:
   * `maubot.client.<mxid>` - Client loggers (Matrix HTTP requests)
   * `maubot.instance.<id>` - Plugin instance loggers
   * `maubot.loader.zip`    - The zip plugin loader (plugins don't
diff --git a/maubot/management/api/spec.yaml b/maubot/management/api/spec.yaml
index af93a65..8bd1206 100644
--- a/maubot/management/api/spec.yaml
+++ b/maubot/management/api/spec.yaml
@@ -399,45 +399,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/client/{id}/avatar':
-    parameters:
-    - name: id
-      in: path
-      description: The Matrix user ID of the client to get
-      required: true
-      schema:
-        type: string
-    post:
-      operationId: upload_avatar
-      summary: Upload a profile picture for a bot
-      tags: [Clients]
-      requestBody:
-        content:
-          image/png:
-            schema:
-              type: string
-              format: binary
-              example: The avatar to upload
-          image/jpeg:
-            schema:
-              type: string
-              format: binary
-              example: The avatar to upload
-      responses:
-        200:
-          description: The avatar was uploaded successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  content_uri:
-                    type: string
-                    description: The MXC URI of the uploaded avatar
-        400:
-          $ref: '#/components/responses/BadRequest'
-        401:
-          $ref: '#/components/responses/Unauthorized'
 
 components:
   responses: