Merge pull request #1556 from turt2live/travis/is/cleanup

Identity Service API cleanup

api/identity/associations.yaml

@@ -62,6 +62,7 @@ paths:
               validated_at:
                 type: integer
                 description: Timestamp indicating the time that the 3pid was validated.
+            required: ['medium', 'address', 'validated_at']
         400:
           description: |-
             The session has not been validated.
@@ -74,6 +75,8 @@ paths:
               "errcode": "M_SESSION_NOT_VALIDATED",
               "error": "This validation session has not yet been completed"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
@@ -81,6 +84,8 @@ paths:
               "errcode": "M_NO_VALID_SESSION",
               "error": "No valid session was found matching that sid and client secret"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/bind":
     post:
       summary: Publish an association between a session and a Matrix user ID.
@@ -158,6 +163,15 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
         400:
           description: |-
             The association was not published.
@@ -170,6 +184,8 @@ paths:
               "errcode": "M_SESSION_NOT_VALIDATED",
               "error": "This validation session has not yet been completed"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
@@ -177,3 +193,5 @@ paths:
               "errcode": "M_NO_VALID_SESSION",
               "error": "No valid session was found matching that sid and client secret"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/email_associations.yaml

@@ -93,12 +93,20 @@ paths:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred.  Some possible errors are:
 
             - ``M_INVALID_EMAIL``: The email address provided was invalid.
             - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_EMAIL",
+              "error": "The email address is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/email/submitToken":
     post:
       summary: Validate ownership of an email address.
@@ -151,6 +159,7 @@ paths:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of an email address.
       description: |-

api/identity/invitation_signing.yaml

@@ -68,9 +68,11 @@ paths:
               signatures:
                 type: object
                 description: The signature of the mxid, sender, and token.
+                $ref: "../../schemas/server-signatures.yaml"
               token:
                 type: string
                 description: The token for the invitation.
+            required: ['mxid', 'sender', 'signatures', 'token']
           examples:
             application/json: {
               "mxid": "@foo:bar.com",
@@ -84,7 +86,10 @@ paths:
             }
         404:
           description: Token was not found.
-          example: {
+          examples: 
+            application/json: {
               "errcode": "M_UNRECOGNIZED",
               "error": "Didn't recognize token"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/lookup.yaml

@@ -55,7 +55,6 @@ paths:
               "not_before": 1428825849161,
               "not_after": 4582425849161,
               "ts": 1428825849161,
-
               "signatures": {
                 "matrix.org": {
                   "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@@ -86,6 +85,15 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
   "/bulk_lookup":
     post:
       summary: Lookup Matrix user IDs for a list of 3pids.
@@ -110,9 +118,11 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 2
+                  maxItems: 2
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address
+                    - type: 3PID Address
                 description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
             required:
               - "threepids"
@@ -134,9 +144,12 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 3
+                  maxItems: 3
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address or the Matrix ID
+                    - type: 3PID Address
+                    - type: Matrix User ID
                 description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -99,12 +99,20 @@ paths:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred. Some possible errors are:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_ADDRESS",
+              "error": "The phone number is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/msisdn/submitToken":
     post:
       summary: Validate ownership of a phone number.
@@ -157,6 +165,7 @@ paths:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of a phone number.
       description: |-

api/identity/pubkey.yaml

@@ -52,6 +52,18 @@ paths:
             properties:
               public_key:
                 type: string
+                description: Unpadded Base64 encoded public key.
+            required: ['public_key']
+        404:
+          description:
+            The public key was not found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "The public key was not found"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/pubkey/isvalid":
     get:
       summary: Check whether a long-term public key is valid.
@@ -80,6 +92,7 @@ paths:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']
   "/pubkey/ephemeral/isvalid":
     get:
       summary: Check whether a short-term public key is valid.
@@ -108,3 +121,4 @@ paths:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']

api/identity/store_invite.yaml

@@ -90,6 +90,7 @@ paths:
               display_name:
                 type: string
                 description: The generated (redacted) display_name.
+            required: ['token', 'public_keys', 'display_name']
             example:
               application/json: {
                 "token": "sometoken",
@@ -112,3 +113,5 @@ paths:
               "error": "Binding already known",
               "mxid": mxid
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

schemas/server-signatures.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 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.
+# 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.
+type: object
+example: {
+  "example.com": {
+    "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+  }
+}
+additionalProperties:
+  type: object
+  title: Server Signatures
+  additionalProperties:
+    type: string

specification/identity_service_api.rst

@@ -23,7 +23,7 @@ user identifiers. From time to time, it is useful to refer to users by other
 number. This identity service specification describes how mappings between
 third-party identifiers and Matrix user identifiers can be established,
 validated, and used. This description technically may apply to any 3pid, but in
-practice has only been applied specifically to email addresses.
+practice has only been applied specifically to email addresses and phone numbers.
 
 .. contents:: Table of Contents
 .. sectnum::
@@ -56,6 +56,75 @@ is left as an exercise for the client.
 
 3PID types are described in `3PID Types`_ Appendix.
 
+API Standards
+-------------
+
+The mandatory baseline for identity service communication in Matrix is exchanging
+JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls
+use a Content-Type of ``application/json``. In addition, strings MUST be encoded as
+UTF-8.
+
+Any errors which occur at the Matrix API level MUST return a "standard error response".
+This is a JSON object which looks like:
+
+.. code:: json
+
+  {
+    "errcode": "<error code>",
+    "error": "<error message>"
+  }
+
+The ``error`` string will be a human-readable error message, usually a sentence
+explaining what went wrong. The ``errcode`` string will be a unique string
+which can be used to handle an error message e.g. ``M_FORBIDDEN``. There may be
+additional keys depending on the error, but the keys ``error`` and ``errcode``
+MUST always be present.
+
+Some standard error codes are below:
+
+:``M_NOT_FOUND``:
+  The resource requested could not be located.
+
+:``M_MISSING_PARAMS``:
+  The request was missing one or more parameters.
+
+:``M_INVALID_PARAM``:
+  The request contained one or more invalid parameters.
+
+:``M_SESSION_NOT_VALIDATED``:
+  The session has not been validated.
+
+:``M_NO_VALID_SESSION``:
+  A session could not be located for the given parameters.
+
+:``M_SESSION_EXPIRED``:
+  The session has expired and must be renewed.
+
+:``M_INVALID_EMAIL``:
+  The email address provided was not valid.
+
+:``M_EMAIL_SEND_ERROR``:
+  There was an error sending an email. Typically seen when attempting to verify
+  ownership of a given email address.
+
+:``M_INVALID_ADDRESS``:
+  The provided third party address was not valid.
+
+:``M_SEND_ERROR``:
+  There was an error sending a notification. Typically seen when attempting to
+  verify ownership of a given third party address.
+
+:``M_UNRECOGNIZED``:
+  The request contained an unrecognised value, such as an unknown token or medium.
+
+:``M_THREEPID_IN_USE``:
+  The third party identifier is already in use by another user. Typically this
+  error will have an additional ``mxid`` property to indicate who owns the
+  third party identifier.
+
+:``M_UNKNOWN``:
+  An unknown error has occurred. 
+
 Privacy
 -------