Spec `?animated` on `/thumbnail` (#1757)

* Spec `?animated` on `/thumbnail`

* v3*

* v1.11

changelogs/client_server/newsfragments/1757.feature

@@ -0,0 +1 @@
+Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).

data/api/client-server/content-repo.yaml

@@ -633,6 +633,28 @@ paths:
           schema:
             type: boolean
             default: false
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server should behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
       responses:
         "200":
           description: A thumbnail of the requested content.
@@ -644,6 +666,9 @@ paths:
                 enum:
                   - image/jpeg
                   - image/png
+                  - image/apng
+                  - image/gif
+                  - image/webp
           content:
             image/jpeg:
               schema:
@@ -651,7 +676,23 @@ paths:
                 description: "**Required.** The bytes for the thumbnail."
             image/png:
               schema:
-                description: "**Required.** The bytes for the thumbnail."
+                x-changedInMatrixVersion:
+                  "1.11": The PNG may be of the APNG variety if animation is supported and requested.
+                description: |
+                  **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
+                  format if `animated=true`.
+            image/apng:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/gif:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/webp:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
         "307":
           description: A redirect to the thumbnail of the requested content.
           headers: