Merge remote-tracking branch 'origin/master' into dbkr/is_bulk_lookup

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

api/identity/lookup.yaml

@@ -1,4 +1,6 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2017 Kamax.io
+# Copyright 2017 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -32,13 +34,13 @@ paths:
           type: string
           name: medium
           required: true
-          description: The literal string "email".
+          description: The medium type of the 3pid. See the `3PID Types`_ Appendix.
           x-example: "email"
         - in: query
           type: string
           name: address
           required: true
-          description: The email address being looked up.
+          description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix.
           x-example: "louise@bobs.burgers"
       responses:
         200:

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
 ======

specification/appendices/threepids.rst

@@ -0,0 +1,48 @@
+.. Copyright 2017 Kamax.io
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+3PID Types
+----------
+Third Party Identifiers (3PIDs) represent identifiers on other namespaces that
+might be associated with a particular person. They comprise a tuple of ``medium``
+which is a string that identifies the namespace in which the identifier exists,
+and an ``address``: a string representing the identifier in that namespace. This
+must be a canonical form of the identifier, *i.e.* if multiple strings could
+represent the same identifier, only one of these strings must be used in a 3PID
+address, in a well-defined manner.
+
+For example, for e-mail, the ``medium`` is 'email' and the ``address`` would be the
+email address, *e.g.* the string ``bob@example.com``. Since domain resolution is
+case-insensitive, the email address ``bob@Example.com`` is also has the 3PID address
+of ``bob@example.com`` (without the capital 'e') rather than ``bob@Example.com``.
+
+The namespaces defined by this specification are listed below. More namespaces
+may be defined in future versions of this specification.
+
+E-Mail
+~~~~~~
+Medium: ``email``
+
+Represents E-Mail addresses. The ``address`` is the raw email address in
+``user@domain`` form with the domain in lowercase. It must not contain other text
+such as real name, angle brackets or a mailto: prefix.
+
+PSTN Phone numbers
+~~~~~~~~~~~~~~~~~~
+Medium: ``msisdn``
+
+Represents telephone numbers on the public switched telephone network.  The
+``address`` is the telephone number represented as a MSISDN (Mobile Station
+International Subscriber Directory Number) as defined by the E.164 numbering
+plan. Note that MSISDNs do not include a leading '+'.

specification/identity_service_api.rst

@@ -1,4 +1,6 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2017 Kamax.io
+.. Copyright 2017 New Vector Ltd
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -52,6 +54,8 @@ necessarily provide evidence that they have validated associations, but claim to
 have done so. Establishing the trustworthiness of an individual identity service
 is left as an exercise for the client.
 
+3PID types are described in `3PID Types`_ Appendix.
+
 Privacy
 -------
 
@@ -291,4 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe
  }
 
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
-.. _`3PID Types`:  ../appendices.html#pid-medium-types
+.. _`3PID Types`:  ../appendices.html#pid-types

specification/targets.yaml

@@ -35,6 +35,7 @@ targets:
       - appendices/base64.rst
       - appendices/signing_json.rst
       - appendices/identifier_grammar.rst
+      - appendices/threepids.rst
       - appendices/threat_model.rst
       - appendices/test_vectors.rst
 groups:  # reusable blobs of files when prefixed with 'group:'