Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-01-11 02:03:41 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Clean up identity service swagger

Browse source 
* 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
This commit is contained in:
Travis Ralston 2018-08-29 20:57:41 -06:00
parent 0130620cc1
commit f030d19f3c
8 changed files with 68 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
api/identity/associations.yaml
View file

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

11
api/identity/email_associations.yaml
View file

@ -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.

19
api/identity/invitation_signing.yaml
View file

@ -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",

19
api/identity/lookup.yaml
View file

@ -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"

11
api/identity/phone_associations.yaml
View file

@ -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.

13
api/identity/ping.yaml
View file

@ -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:

7
api/identity/pubkey.yaml
View file

@ -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:

13
api/identity/store_invite.yaml
View file

@ -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"