diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index ebb63ba4..e8f23c12 100644 --- a/api/client-server/content-repo.yaml +++ b/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 diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 385e8a60..285844c0 100644 --- a/api/identity/lookup.yaml +++ b/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: diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 10387c56..e428605e 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -63,6 +63,9 @@ - ``GET /account/whoami`` (`#1063 `_). + - ``GET /media/{version}/preview_url`` + (`#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 `_). + - Clarify rate limiting and security for content repository. + (`#1064 `_). r0.2.0 ====== diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst new file mode 100644 index 00000000..84860740 --- /dev/null +++ b/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 '+'. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 85b9789f..19275593 100644 --- a/specification/identity_service_api.rst +++ b/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 diff --git a/specification/targets.yaml b/specification/targets.yaml index fb68e13d..62799afe 100644 --- a/specification/targets.yaml +++ b/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:'