Clean up identity service swagger

* Add `consumes` (swagger) * Remove `http` as a supported scheme (the spec specifically says clients MUST use https) * Clarify various descriptions * Full stops * Additional wording * s/older versions/previous drafts - we haven't had a release yet * Indentation on examples
6 years ago · f030d19f3c
parent 0130620cc1
commit f030d19f3c
8 changed files with 68 additions and 45 deletions
--- a/api/identity/associations.yaml
+++ b/api/identity/associations.yaml
@ -18,15 +18,17 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
  "/3pid/getValidated3pid":
    get:
      summary: Check whether ownership of a 3pid was validated.
-      description: A client can check whether ownership of a 3pid was validated
+      description: |-
+        Determines if a given 3pid has been validated by a user.
      operationId: getValidated3pid
      parameters:
        - in: query
@ -61,7 +63,9 @@ paths:
                description: The address of the 3pid being looked up.
              validated_at:
                type: integer
-                description: Timestamp indicating the time that the 3pid was validated.
+                description: |-
+                  Timestamp, in milliseconds, indicating the time that the 3pid
+                  was validated.
            required: ['medium', 'address', 'validated_at']
        400:
          description: |-
@ -78,7 +82,7 @@ paths:
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"
        404:
-          description: The Session ID or client secret were not found
+          description: The Session ID or client secret were not found.
          examples:
            application/json: {
              "errcode": "M_NO_VALID_SESSION",
@ -95,7 +99,7 @@ paths:
        Future calls to ``/lookup`` for any of the session\'s 3pids will return
        this association.

-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data.  However, this usage is
        deprecated.
@ -132,7 +136,6 @@ paths:
              "not_before": 1428825849161,
              "not_after": 4582425849161,
              "ts": 1428825849161,
-
              "signatures": {
                "matrix.org": {
                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@ -162,7 +165,10 @@ paths:
                description: The unix timestamp at which the association was verified.
              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.
+                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
--- a/api/identity/email_associations.yaml
+++ b/api/identity/email_associations.yaml
@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
@ -34,13 +35,13 @@ paths:
        that that user was able to read the email for that email address, and
        so we validate ownership of the email address.

-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
        additional behaviour on top, for example,
        ``/register/email/requestToken`` is designed specifically for use when
        registering an account and therefore will inform the user if the email
        address given is already registered on the server.

-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data.  However, this usage is
        deprecated.
@ -58,7 +59,7 @@ paths:
            properties:
              client_secret:
                type: string
-                description: A unique string used to identify the validation attempt
+                description: A unique string used to identify the validation attempt.
              email:
                type: string
                description: The email address to validate.
@ -119,7 +120,7 @@ paths:
        associate the email address with any Matrix user ID. Specifically,
        calls to ``/lookup`` will not show a binding.

-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data.  However, this usage is
        deprecated.
--- a/api/identity/invitation_signing.yaml
+++ b/api/identity/invitation_signing.yaml
@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
@ -29,7 +30,7 @@ paths:
      description: |-
        Sign invitation details.

-        The identity server will look up ``token`` which was stored in a call
+        The identity service will look up ``token`` which was stored in a call
        to ``store-invite``, and fetch the sender of the invite.
      operationId: blindlySignStuff
      parameters:
@ -38,24 +39,24 @@ paths:
          schema:
            type: object
            example: {
-                "mxid": "@foo:bar.com",
-                "token": "sometoken",
-                "private_key": "base64encodedkey"
-              }
+              "mxid": "@foo:bar.com",
+              "token": "sometoken",
+              "private_key": "base64encodedkey"
+            }
            properties:
              mxid:
                type: string
                description: The Matrix user ID of the user accepting the invitation.
              token:
                type: string
-                description: Token from the call to ``store-invite``
+                description: The token from the call to ``store-invite``.
              private_key:
                type: string
                description: The private key, encoded as `Unpadded base64`_.
            required: ["mxid", "token", "private_key"]
      responses:
        200:
-          description: The signedjson of the mxid, sender, and token.
+          description: The signed JSON of the mxid, sender, and token.
          schema:
            type: object
            properties:
@ -85,7 +86,7 @@ paths:
              "token": "abc123"
            }
        404:
-          description: Token was not found.
+          description: The token was not found.
          examples: 
            application/json: {
              "errcode": "M_UNRECOGNIZED",
--- a/api/identity/lookup.yaml
+++ b/api/identity/lookup.yaml
@ -1,6 +1,7 @@
 # Copyright 2016 OpenMarket Ltd
 # Copyright 2017 Kamax.io
 # Copyright 2017 New Vector Ltd
+# 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.
@ -20,8 +21,9 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
@ -46,7 +48,7 @@ paths:
      responses:
        200:
          description:
-            The association for that 3pid, or the empty object if no association is known.
+            The association for that 3pid, or an empty object if no association is known.
          examples:
            application/json: {
              "address": "louise@bobs.burgers",
@ -66,10 +68,10 @@ paths:
            properties:
              address:
                type: string
-                description: The 3pid address of the user being looked up.
+                description: The 3pid address of the user being looked up, matching the address requested.
              medium:
                type: string
-                description: The literal string "email".
+                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
              mxid:
                type: string
                description: The Matrix user ID associated with the 3pid.
@ -126,7 +128,9 @@ paths:
                    #- type: 3PID Address
                    - type: string
                    - type: string
-                description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
+                description: |-
+                  An array of arrays containing the `3PID Types`_ with the ``medium``
+                  in first position and the ``address`` in second position.
            required:
              - "threepids"
      responses:
@ -157,6 +161,9 @@ paths:
                    - type: string
                    - type: string
                    - type: string
-                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.
+                description: |-
+                  An array of array containing the `3PID Types`_ with the ``medium``
+                  in first position, the ``address`` in second position and Matrix user
+                  ID in third position.
            required:
              - "threepids"
--- a/api/identity/phone_associations.yaml
+++ b/api/identity/phone_associations.yaml
@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
@ -34,13 +35,13 @@ paths:
        indicates that that user was able to read the SMS for that phone
        number, and so we validate ownership of the phone number.

-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
        additional behaviour on top, for example,
        ``/register/msisdn/requestToken`` is designed specifically for use when
        registering an account and therefore will inform the user if the phone
        number given is already registered on the server.

-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data. However, this usage is
        deprecated.
@ -106,6 +107,8 @@ paths:

            - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
            - ``M_SEND_ERROR``: The validation SMS could not be sent.
+            - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
+              SMS to the provided country or region.
          examples:
            application/json: {
              "errcode": "M_INVALID_ADDRESS",
@ -125,7 +128,7 @@ paths:
        associate the phone number address with any Matrix user
        ID. Specifically, calls to ``/lookup`` will not show a binding.

-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data. However, this usage is
        deprecated.
--- a/api/identity/ping.yaml
+++ b/api/identity/ping.yaml
@ -1,4 +1,5 @@
 # Copyright 2018 Kamax Sàrl
+# 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.
@ -14,7 +15,7 @@

 swagger: "2.0"
 info:
-  title: "Matrix Client-Identity Versions API"
+  title: "Matrix Identity Service Ping API"
  version: "1.0.0"
 host: localhost:8090
 schemes:
@ -25,19 +26,19 @@ produces:
 paths:
  "/api/v1":
    get:
-      summary: Checks that an Identity server is available at this API endpopint.
+      summary: Checks that an Identity Service is available at this API endpoint.
      description: |-
-        Checks that an Identity server is available at this API endpopint.
+        Checks that an Identity Service is available at this API endpoint.

-        To discover that an Identity server is available at a specific URL,
+        To discover that an Identity Service is available at a specific URL,
        this endpoint can be queried and will return an empty object.

        This is primarly used for auto-discovery and health check purposes
-        by entities acting as a client for the Identity server.
+        by entities acting as a client for the Identity Service.
      operationId: ping
      responses:
        200:
-          description: An Identity server is ready to serve requests.
+          description: An Identity Service is ready to serve requests.
          examples:
            application/json: {}
          schema:
--- a/api/identity/pubkey.yaml
+++ b/api/identity/pubkey.yaml
@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
@ -113,8 +114,8 @@ paths:
            The validity of the public key.
          examples:
            application/json: {
-                "valid": true
-              }
+              "valid": true
+            }
          schema:
            type: object
            properties:
--- a/api/identity/store_invite.yaml
+++ b/api/identity/store_invite.yaml
@ -18,16 +18,17 @@ info:
 host: localhost:8090
 schemes:
  - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
  - application/json
 paths:
  "/store-invite":
    post:
-      summary: Store pending invitations to a user\'s 3pid.
+      summary: Store pending invitations to a user's 3pid.
      description: |-
-        Store pending invitations to a user\'s 3pid.
+        Store pending invitations to a user's 3pid.

        In addition to the request parameters specified below, an arbitrary
        number of other parameters may also be specified. These may be used in
@ -47,6 +48,8 @@ paths:

        Also, the generated ephemeral public key will be listed as valid on
        requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
+
+        Currently, invites may only be issued for 3pids of the ``email`` medium.
      operationId: storeInvite
      parameters:
        - in: body
@ -84,7 +87,7 @@ paths:
                description: The generated token.
              public_keys:
                type: array
-                description: A list of [server\'s long-term public key, generated ephemeral public key].
+                description: A list of [server's long-term public key, generated ephemeral public key].
                items:
                  type: string
              display_name:
@ -111,7 +114,7 @@ paths:
            application/json: {
              "errcode": "M_THREEPID_IN_USE",
              "error": "Binding already known",
-              "mxid": mxid
+              "mxid": "@alice:example.com"
            }
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"