Spec URL previews (#1064)

* Spec URL previews
* Require authentication on /upload and /preview_url

api/client-server/content-repo.yaml

@@ -18,15 +18,23 @@ info:
 host: localhost:8008
 schemes:
   - https
+  - http
 basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+  - "*/*"
 produces:
   - application/json
   - "*/*"
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/upload":
     post:
       summary: Upload some content to the content repository.
       produces: ["application/json"]
+      security:
+        - accessToken: []
       parameters:
         - in: header
           name: Content-Type
@@ -60,6 +68,10 @@ paths:
             application/json: {
                 "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
               }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}":
@@ -93,6 +105,10 @@ paths:
               type: "string"
           schema:
             type: file
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
@@ -133,6 +149,10 @@ paths:
               type: "string"
           schema:
             type: file
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
@@ -184,5 +204,63 @@ paths:
               enum: ["image/jpeg", "image/png"]
           schema:
             type: file
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media
+  "/preview_url":
+    get:
+      summary: "Get information about a URL for a client"
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          x-example: "https://matrix.org"
+          name: url
+          description: "The URL to get a preview of"
+          required: true
+        - in: query
+          type: number
+          x-example: 1510610716656
+          name: ts
+          description: |-
+            The preferred point in time to return a preview for. The server may
+            return a newer version if it does not have the requested version
+            available.
+      responses:
+        200:
+          description: |-
+            The OpenGraph data for the URL, which may be empty. Some values are
+            replaced with matrix equivalents if they are provided in the response.
+            The differences from the OpenGraph protocol are described here.
+          schema:
+            type: object
+            properties:
+              "matrix:image:size":
+                type: number
+                description: |-
+                  The byte-size of the image. Omitted if there is no image attached.
+              "og:image":
+                type: string
+                description: |-
+                  An MXC URI to the image. Ommitted if there is no image.
+          examples:
+            application/json: {
+                "og:title": "Matrix Blog Post",
+                "og:description": "This is a really cool blog post from matrix.org",
+                "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
+                "og:image:type": "image/png",
+                "og:image:height": 48,
+                "og:image:width": 48,
+                "matrix:image:size": 102400
+              }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Media

changelogs/client_server.rst

@@ -63,6 +63,9 @@
     - ``GET /account/whoami``
       (`#1063 <https://github.com/matrix-org/matrix-doc/pull/1063>`_).
 
+    - ``GET /media/{version}/preview_url``
+      (`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).
+
 - Spec clarifications:
 
   - Add endpoints and logic for invites and third-party invites to the federation
@@ -99,6 +102,8 @@
   - Clarify the relationship between ``username`` and ``user_id`` in the
     ``/register`` API
     (`#1032 <https://github.com/matrix-org/matrix-doc/pull/1032>`_).
+  - Clarify rate limiting and security for content repository.
+    (`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).
 
 r0.2.0
 ======