Move upload/download API doc from api.yaml

jagerman · jagerman · commit 03f8dad944a3 · 2022-03-14T18:51:18.000-03:00
diff --git a/api.yaml b/api.yaml
@@ -16,206 +16,6 @@ externalDocs:
   description: Find out more about the Oxen project
   url: http://oxen.io
 paths:
-  /room/{roomToken}/file:
-    post:
-      tags: [Files]
-      summary: "Uploads a file to a room."
-      description: >
-        Takes the request as binary in the body and takes other properties via submitted headers.
-        This saves space, particularly for large uploads.  The user must have upload and posting
-        permissions for the room.  The file will have a default lifetime of 1 hour, but that is
-        extended to 15 days when the containing message referencing the uploaded file is posted.
-        
-        
-        See also the `.../fileJson` endpoint for submitting via a json body.
-      parameters:
-      - $ref: "#/components/parameters/pathRoomToken"
-      - name: X-Filename
-        in: header
-        description: >
-          Suggested filename of the upload.  Typically the basename of the file uploaded from the
-          user.
-        schema:
-          type: string
-      requestBody:
-        description: The file content, in bytes.
-        required: true
-        content:
-          '*/*':
-            {}
-      responses:
-        200:
-          description: successful operation
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id:
-                    type: integer
-                    format: int64
-                    description: "The id of the file on the server."
-        403:
-          description: >
-            Upload forbidden.  This response code indicates that the user does not have posting
-            and/or upload permissions in the room either because of room settings, user restriction,
-            or because the user is banned.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  banned:
-                    type: boolean
-                    description: >
-                      True if the upload was denied because the user is banned, omitted otherwise.
-                  noWrite:
-                    type: boolean
-                    description: >
-                      True if the upload was denied because the user does not have write access to
-                      the room (but is not banned).  Omitted otherwise.
-                  noUpload:
-                    type: boolean
-                    description: >
-                      True if the upload was denied because the user does not have upload access to
-                      the room (but is not banned and has write permissions).  Omitted otherwise.
-
-  /room/{roomToken}/fileJSON:
-    post:
-      tags: [Files]
-      summary: "Uploads a file to a room using a JSON encoded body."
-      description: >
-        This is less efficient when a binary upload is possible because the body must be passed as
-        base64-encoded data (which is 33% larger).  The user must have upload and posting
-        permissions for the room.  [NOT YET IMPLEMENTED: The file will have a default lifetime of 1
-          hour, but that is extended to 15 days when the containing message referencing the upload
-          is submitted.]
-      parameters:
-      - $ref: "#/components/parameters/pathRoomToken"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [filename, content]
-              properties:
-                filename:
-                  type: string
-                  description: "Suggested filename of the upload.  Typically the basename of the file uploaded from the user."
-                content:
-                  type: string
-                  format: byte
-                  description: The file content, in base64 encoding.
-      responses:
-        200:
-          $ref: "#/paths/~1room~1%7BroomToken%7D~1file/post/responses/200"
-        403:
-          $ref: "#/paths/~1room~1%7BroomToken%7D~1file/post/responses/403"
-
-  /room/{roomToken}/file/{fileId}:
-    get:
-      tags: [Files]
-      summary: "Retrieves a file from the room via JSON."
-      description: >
-        Retrieves a file via a fileId from the room via a JSON object response.  This is noticeably
-        less efficient (particularly for large files) than the binary version when making direct
-        requests because the file data must be encoded using base64 encoding.
-      parameters:
-        - $ref: "#/components/parameters/pathRoomToken"
-        - $ref: "#/components/parameters/pathFileId"
-      responses:
-        200:
-          description: successful operation; returns the file in JSON.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  filename:
-                    type: string
-                    description: >
-                      The suggested filename of the file. Omitted if the file was uploaded without a
-                      filename (e.g. from older clients, or clients that specify an empty filename.)
-                  size:
-                    type: integer
-                    format: int64
-                    description: >
-                      The file size, in bytes. (*Not* the length of the base64-encoded data.)
-                  uploaded:
-                    type: number
-                    format: double
-                    description: The unix timestamp when the file was uploaded.
-                  expires:
-                    type: number
-                    format: double
-                    nullable: true
-                    description: >
-                      The unix timestamp when the file is scheduled to be removed.  Will be null if
-                      the attachment is permanent, such as for room images or attachments in pinned
-                      messages.
-        403:
-          $ref: "#/paths/~1room~1%7BroomToken%7D/get/responses/403"
-        404:
-          description: >
-            The referenced file does not exist.  (It may have expired, or may be invalid.)
-
-  /room/{roomToken}/file/{fileId}/{filename}:
-    get:
-      tags: [Files]
-      summary: "Retrieves a file from the room as binary."
-      description: >
-        Retrieves a file via a fileId from the room, returning the file content directly as the
-        binary response body.  The filename parameter is ignored and may be empty: it is primarily
-        included to aid in clients that want the request to include a filename, and differentiates
-        this as a request retrieving the file itself rather than the file as a JSON response.  See
-        the version without `/filename` for a JSON-returning version.
-      parameters:
-        - $ref: "#/components/parameters/pathRoomToken"
-        - $ref: "#/components/parameters/pathFileId"
-        - name: filename
-          in: path
-          required: true
-          description: >
-            Filename if known by the requesting client, and empty otherwise.  The value of this
-            parameter is ignored by the server itself: it is included to differentiate this request
-            from the JSON version, and so that clients may include a filename in the request URL for
-            contexts where that is useful.
-          schema:
-            type: integer
-            format: int64
-      responses:
-        200:
-          description: successful operation; returns the file, in raw bytes.
-          headers:
-            Content-Length:
-              description: The size of the file.
-              schema:
-                type: integer
-                format: int64
-              example: 12345
-            Date:
-              description: The HTTP timestamp at which the file was uploaded.
-              schema:
-                type: string
-                example: "Thu, 7 Oct 2021 00:42:00 GMT"
-            Expires:
-              description: >
-                The HTTP timestamp at which the file is scheduled to expire.  This header is omitted
-                if the attachment is non-expiring (e.g. for attachments in a pinned message [NOT YET
-                IMPLEMENTED]).
-              schema:
-                type: string
-                example: "Fri, 22 Oct 2021 00:42:42 GMT"
-          content:
-            application/octet-stream:
-              schema:
-                type: string
-                format: binary
-        403:
-          $ref: "#/paths/~1room~1%7BroomToken%7D~1file~1%7BfileId%7D/get/responses/403"
-        404:
-          $ref: "#/paths/~1room~1%7BroomToken%7D~1file~1%7BfileId%7D/get/responses/404"
   /user/{sessionId}/permission:
     post:
       tags: [Users]
diff --git a/sogs/routes/rooms.py b/sogs/routes/rooms.py
@@ -354,7 +354,70 @@ def poll_room_info(room, info_updated):
 @rooms.post("/room/<Room:room>/file")
 @auth.user_required
 def upload_file(room):
-    """ upload a file to a room """
+    """
+    Uploads a file to a room.
+
+    Takes the request as binary in the body and takes other properties (specifically the suggested
+    filename) via submitted headers.
+
+    The user must have upload and posting permissions for the room.  The file will have a default
+    lifetime of 1 hour, which is extended to 15 days (by default) when a post referencing the
+    uploaded file is posted or edited.
+
+    # URL Parameters
+
+    # Body
+
+    The body of the request is the raw bytes that make up the attachment body.
+
+    # Header parameters
+
+    ## Content-Type
+
+    This should be set to application/octet-stream.  If the client has a strong reason to use
+    another content type then it may do so, but it is acceptable to always use
+    `application/octet-stream`.
+
+    ## Content-Disposition
+
+    The attachment filename should be provided via the `Content-Disposition` header of the request,
+    encoded as URI-encoded UTF-8 as per RFC 5987.  Specifically, it should be formatted as:
+
+        Content-Disposition: attachment; filename*=UTF-8''filename.txt
+
+    where `filename.txt` is a utf-8 byte sequence with any bytes not in the following list encoded
+    using %xx URI-style encoding.
+
+    Non-encoded ascii characters: A-Z, a-z, 0-9, !, #, $, &, +, -, ., ^, _, `, |, ~.  All other
+    characters shall be represented as their utf-8 byte sequence.
+
+    For instance, a file named `my 🎂.txt` (🎂 = U+1F382, with utf-8 representation 0xF0 0x9F 0x8E
+    0x82) should specify the filename in the header as:
+
+        Content-Disposition: attachment; filename*=UTF-8''my%20%f0%9f%8e%82.txt
+
+    Filenames are not required as they are not always available (such as when uploading a pasted
+    image) but should be used when possible.
+
+    The filename, if provided, will be provided in the same format in the download header for the
+    file.
+
+    # Error status codes
+
+    - 403 Forbidden — Returned if the current user does not have permission to post messages or
+      upload files to the room.
+
+    - 404 Not Found — Returned if the room does not exist, or is configured as inaccessible (and
+      this user doesn't have access).
+
+    # Return value
+
+    On successful upload this endpoint returns a 201 (Created) status code (*not* 200), with a JSON
+    body containing an object with key:
+
+    - `id` — the numeric id of the upload.  If the id is not referenced via a subsequent new post,
+      post edit, or room image request within one hour then the attachment will be deleted.
+    """
 
     if not room.check_upload(g.user):
         abort(http.FORBIDDEN)
@@ -375,11 +438,58 @@ def upload_file(room):
 
 
 @rooms.get("/room/<Room:room>/file/<int:fileId>")
-@rooms.get("/room/<Room:room>/file/<int:fileId>/<filename>")
 @auth.read_required
-def serve_file(room, fileId, filename=None):
+def serve_file(room, fileId):
     """
-    serves a file uploaded to a room
+    Retrieves a file uploaded to the room.
+
+    Retrieves a file via its numeric id from the room, returning the file content directly as the
+    binary response body.  The file's suggested filename (as provided by the uploader) is provided
+    in the Content-Disposition header, if available.
+
+    # URL Parameters
+
+    - `fileId` — The id of the attachment to download.
+
+    # Return value
+
+    On success the file content is returned as bytes in the response body.  Additional information
+    is provided via response headers:
+
+    ## Content-Length
+
+    The size (in bytes) of the attachment.
+
+    ## Content-Type
+
+    Always `application-octet-stream` (even if the uploader specified something else).
+
+    ## Content-Disposition
+
+    This specifies the suggested filename as provided by the uploader, if present.  The filename is
+    encoded using standard RFC 5987 encoding, for example:
+
+        Content-Disposition: attachment; filename*=UTF-8''filename.txt
+
+    See [the upload endpoint](#post-roomroomfile) for filename encoding details.  If the attachment
+    was uploaded without a filename then this header will not include the filename component, i.e.:
+
+        Content-Disposition: attachment
+
+    ## Date
+
+    The timestamp at which this file was uploaded, as a standard HTTP date.
+
+    ## Expires
+
+    The timestamp at which this file is currently scheduled to expire, as a standard HTTP date.
+
+    # Error status codes
+
+    - 403 Forbidden — Returned if the current user does not have permission to read messages in the
+      room, e.g. because they are banned or the room permissions otherwise restrict access.
+
+    - 404 Not Found — Returned if the attachment does not exist in this room (or has expired).
     """
     room_file = room.get_file(fileId)
     if not room_file:
@@ -402,3 +512,26 @@ def serve_file(room, fileId, filename=None):
     return Response(
         response=f, status=200, content_type='application/octet-stream', headers=headers
     )
+
+
+@rooms.get("/room/<Room:room>/file/<int:fileId>/<filename>")
+@auth.read_required
+def serve_file_with_ignored_filename(room, fileId, filename):
+    """
+    Convenience endpoint for downloading file with a filename appended to the URL.
+
+    This endpoint is exactly identical to the version of the endpoint without a filename: the
+    suffixed filename in the request is simply ignored.  This alias is provided only to make it
+    slightly more convenient to construct a URL containing a known filename, such as when using
+    command-line tools for debugging.
+
+    Most clients should simply use the non-suffixed endpoint instead.
+
+    # URL Parameters
+
+    - `fileId` — The id of the attachment to download.
+
+    - `filename` — Arbitrary filename of the attachment; this value is entirely ignored by SOGS.
+
+    """
+    return serve_file(room=room, fileId=fileId)
