Merge pull request #2068 from matrix-org/travis/1.0/mxc

Refactor documentation for content/media repository

api/client-server/content-repo.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2019 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -58,18 +59,41 @@ paths:
             format: byte
       responses:
         200:
-          description: The MXC URI for the uploaded content.
+          description: The `MXC URI`_ for the uploaded content.
           schema:
             type: object
             required: ["content_uri"]
             properties:
               content_uri:
                 type: string
-                description: "The MXC URI to the uploaded content."
+                description: "The `MXC URI`_ to the uploaded content."
           examples:
             application/json: {
-                "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
-              }
+              "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
+            }
+        403:
+          description: |-
+            The user does not have permission to upload the content. Some reasons for this error include:
+
+            - The server does not permit the file type.
+            - The user has reached a quota for uploaded content.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Cannot upload this content"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        413:
+          description: |-
+            The uploaded content is too large for the server.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Cannot upload files larger than 100mb"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
@@ -114,10 +138,23 @@ paths:
               description: "The content type of the file that was previously uploaded."
               type: "string"
             Content-Disposition:
-              description: "The name of the file that was previously uploaded, if set."
+              description: |-
+                The name of the file that was previously uploaded, if set.
               type: "string"
           schema:
             type: file
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the uploaded file."
+        502:
+          description: |-
+            The content is too large for the server to serve.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to serve"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
@@ -126,7 +163,9 @@ paths:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
     get:
-      summary: "Download content from the content repository as a given filename."
+      summary: |-
+        Download content from the content repository. This is the same as
+        the download endpoint above, except permitting a desired file name.
       operationId: getContentOverrideName
       produces: ["*/*"]
       parameters:
@@ -149,8 +188,7 @@ paths:
           name: fileName
           x-example: filename.jpg
           required: true
-          description: |
-            The filename to give in the Content-Disposition
+          description: A filename to give in the ``Content-Disposition`` header.
         - in: query
           type: boolean
           name: allow_remote
@@ -169,10 +207,24 @@ paths:
               description: "The content type of the file that was previously uploaded."
               type: "string"
             Content-Disposition:
-              description: "The name of file given in the request"
+              description: |-
+                The ``fileName`` requested or the name of the file that was previously
+                uploaded, if set.
               type: "string"
           schema:
             type: file
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the uploaded file."
+        502:
+          description: |-
+            The content is too large for the server to serve.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to serve"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
@@ -181,15 +233,17 @@ paths:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
-      summary: "Download a thumbnail of the content from the content repository."
+      summary: |-
+        Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
+        section for more information.
       operationId: getContentThumbnail
       produces: ["image/jpeg", "image/png"]
       parameters:
         - in: path
           type: string
           name: serverName
           required: true
-          x-example: matrix.org
+          x-example: example.org
           description: |
             The server name from the ``mxc://`` URI (the authoritory component)
         - in: path
@@ -205,22 +259,24 @@ paths:
           name: width
           required: true
           description: |-
-            The *desired* width of the thumbnail. The actual thumbnail may not
-            match the size specified.
+            The *desired* width of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
         - in: query
           type: integer
           x-example: 64
           name: height
           required: true
           description: |-
-            The *desired* height of the thumbnail. The actual thumbnail may not
-            match the size specified.
+            The *desired* height of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
         - in: query
           type: string
           enum: ["crop", "scale"]
           name: method
           x-example: "scale"
-          description: The desired resizing method.
+          description: |-
+            The desired resizing method. See the `thumbnailing <#thumbnails>`_
+            section for more information.
         - in: query
           type: boolean
           name: allow_remote
@@ -241,6 +297,40 @@ paths:
               enum: ["image/jpeg", "image/png"]
           schema:
             type: file
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the thumbnail."
+        400:
+          description: |-
+            The request does not make sense to the server, or the server cannot thumbnail
+            the content. For example, the client requested non-integer dimensions or asked
+            for negatively-sized images.
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN",
+              "error": "Cannot generate thumbnails for the requested content"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        413:
+          description: |-
+            The local content is too large for the server to thumbnail.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to thumbnail"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        502:
+          description: |-
+            The remote content is too large for the server to thumbnail.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to thumbnail"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
@@ -259,7 +349,7 @@ paths:
           type: string
           x-example: "https://matrix.org"
           name: url
-          description: "The URL to get a preview of"
+          description: "The URL to get a preview of."
           required: true
         - in: query
           type: integer
@@ -287,7 +377,7 @@ paths:
               "og:image":
                 type: string
                 description: |-
-                  An MXC URI to the image. Omitted if there is no image.
+                  An `MXC URI`_ to the image. Omitted if there is no image.
           examples:
             application/json: {
                 "og:title": "Matrix Blog Post",

api/client-server/room_state.yaml

@@ -75,7 +75,7 @@ paths:
             type: object
             example: {
                 "membership": "join",
-                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
+                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
                 "displayname": "Alice Margatroid"
               }
       responses:

changelogs/client_server/newsfragments/2068.clarification

@@ -0,0 +1 @@
+Clarify how the content repository works, and what it is used for.

event-schemas/examples/m.room.member

@@ -4,7 +4,7 @@
   "type": "m.room.member",
   "content": {
     "membership": "join",
-    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
+    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
     "displayname": "Alice Margatroid"
   }
 }

event-schemas/examples/m.room.member$invite_room_state

@@ -2,7 +2,7 @@
   "$ref": "m.room.member",
   "content": {
     "membership": "invite",
-    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
+    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
     "displayname": "Alice Margatroid"
   },
   "unsigned": {

event-schemas/examples/m.room.member$third_party_invite

@@ -2,7 +2,7 @@
   "$ref": "m.room.member",
   "content": {
     "membership": "invite",
-    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
+    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
     "displayname": "Alice Margatroid",
     "third_party_invite": {
       "display_name": "alice",

event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -19,8 +19,8 @@ properties:
     type: integer
   thumbnail_url:
     description: |-
-      The URL to a thumbnail of the image. Only present if the
-      thumbnail is unencrypted.
+      The URL (typically `MXC URI`_) to a thumbnail of the image.
+      Only present if the thumbnail is unencrypted.
     type: string
   thumbnail_file:
     description: |-

event-schemas/schema/m.room.message$m.audio

@@ -27,7 +27,9 @@ properties:
           - m.audio
         type: string
       url:
-        description: Required if the file is not encrypted. The URL to the audio clip.
+        description: |-
+          Required if the file is not encrypted. The URL (typically `MXC URI`_)
+          to the audio clip.
         type: string
       file:
         description: |-

event-schemas/schema/m.room.message$m.file

@@ -42,7 +42,9 @@ properties:
           - m.file
         type: string
       url:
-        description: Required if the file is unencrypted. The URL to the file.
+        description: |-
+          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          to the file.
         type: string
       file:
         description: |-

event-schemas/schema/m.room.message$m.image

@@ -17,7 +17,9 @@ properties:
           - m.image
         type: string
       url:
-        description: Required if the file is unencrypted. The URL to the image.
+        description: |-
+          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          to the image.
         type: string
       file:
         description: |-

event-schemas/schema/m.room.message$m.video

@@ -28,8 +28,8 @@ properties:
             type: integer
           thumbnail_url:
             description: |-
-              The URL to an image thumbnail of the video clip. Only present if the
-              thumbnail is unencrypted.
+              The URL (typically `MXC URI`_) to an image thumbnail of
+              the video clip. Only present if the thumbnail is unencrypted.
             type: string
           thumbnail_file:
             description: |-
@@ -48,7 +48,9 @@ properties:
           - m.video
         type: string
       url:
-        description: Required if the file is unencrypted. The URL to the video clip.
+        description: |-
+          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          to the video clip.
         type: string
       file:
         description: |-