wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add operationId to all endpoints of all APIs

Browse source 
To facilitate generation of API stubs from the spec.

Signed-off-by: Alexey Rusakov <ktirf@users.sf.net>
This commit is contained in:
Kitsune Ral 2017-08-03 08:19:34 +09:00
parent bf3b49f13c
commit 24afe7987c
47 changed files with 95 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

1
api/application-service/application_service.yaml
View file

@ -31,6 +31,7 @@ paths:
description: |-
This API is called by the HS when the HS wants to push an event (or
batch of events) to the AS.
operationId: sendTransaction
parameters:
- in: path
name: txnId

2
api/client-server/account-data.yaml
View file

@ -34,6 +34,7 @@ paths:
Set some account_data for the client. This config is only visible to the user
that set the account_data. The config will be synced to clients in the
top-level ``account_data``.
operationId: setAccountData
security:
- accessToken: []
parameters:
@ -75,6 +76,7 @@ paths:
Set some account_data for the client on a given room. This config is only
visible to the user that set the account_data. The config will be synced to
clients in the per-room ``account_data``.
operationId: setAccountDataPerRoom
security:
- accessToken: []
parameters:

1
api/client-server/admin.yaml
View file

@ -36,6 +36,7 @@ paths:
This API may be restricted to only be called by the user being looked
up, or by a server admin. Server-local administrator privileges are not
specified in this document.
operationId: getWhoIs
security:
- accessToken: []
parameters:

3
api/client-server/administrative_contact.yaml
View file

@ -39,6 +39,7 @@ paths:
Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password.
operationId: getAccount3PIDs
security:
- accessToken: []
responses:
@ -74,6 +75,7 @@ paths:
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
operationId: post3PIDs
security:
- accessToken: []
parameters:
@ -139,6 +141,7 @@ paths:
validation tokens when adding an email address to an account. This API's
parameters and response is identical to that of the HS API
|/register/email/requestToken|_ endpoint.
operationId: requestTokenTo3PID
responses:
200:
description: An email was sent to the given address

2
api/client-server/banning.yaml
View file

@ -36,6 +36,7 @@ paths:
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
The caller must have the required power level in order to perform this operation.
operationId: ban
security:
- accessToken: []
parameters:
@ -91,6 +92,7 @@ paths:
and join if they would otherwise be allowed to join according to its join rules.
The caller must have the required power level in order to perform this operation.
operationId: unban
security:
- accessToken: []
parameters:

1
api/client-server/cas_login_redirect.yaml
View file

@ -37,6 +37,7 @@ paths:
``redirectUrl=https://client.example.com/?q=p``, it might redirect to
``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``.
operationId: redirectToCAS
parameters:
- in: query
type: string

1
api/client-server/cas_login_ticket.yaml
View file

@ -39,6 +39,7 @@ paths:
If validation is unsuccessful, the server should respond with a ``401
Unauthorized`` error, the body of which will be displayed to the user.
operationid: loginByCASTicket
parameters:
- in: query
type: string

4
api/client-server/content-repo.yaml
View file

@ -26,6 +26,7 @@ paths:
"/upload":
post:
summary: Upload some content to the content repository.
operationid: uploadContent
produces: ["application/json"]
parameters:
- in: header
@ -65,6 +66,7 @@ paths:
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
operationId: getContent
produces: ["*/*"]
parameters:
- in: path
@ -98,6 +100,7 @@ paths:
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: "Download content from the content repository as a given filename."
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
- in: path
@ -138,6 +141,7 @@ paths:
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
- in: path

1
api/client-server/create_room.yaml
View file

@ -46,6 +46,7 @@ paths:
4. Invite events implied by ``invite`` and ``invite_3pid``.
operationId: createRoom
security:
- accessToken: []
parameters:

4
api/client-server/device_management.yaml
View file

@ -33,6 +33,7 @@ paths:
summary: List registered devices for the current user
description: |-
Gets information about all devices for the current user.
operationId: getDevices
security:
- accessToken: []
responses:
@ -66,6 +67,7 @@ paths:
summary: Get a single device
description: |-
Gets information on a single device, by device id.
operationId: getDevice
security:
- accessToken: []
parameters:
@ -97,6 +99,7 @@ paths:
summary: Update a device
description: |-
Updates the metadata on the given device.
operationId: updateDevice
security:
- accessToken: []
parameters:
@ -137,6 +140,7 @@ paths:
This API endpoint uses the `User-Interactive Authentication API`_.
Deletes the given device, and invalidates any access token assoicated with it.
operationId: deleteDevice
security:
- accessToken: []
parameters:

3
api/client-server/directory.yaml
View file

@ -30,6 +30,7 @@ paths:
"/room/{roomAlias}":
put:
summary: Create a new mapping from room alias to room ID.
operationId: setRoomAlias
security:
- accessToken: []
parameters:
@ -78,6 +79,7 @@ paths:
domain part of the alias does not correspond to the server's own
domain.
operationId: getRoomIdByAlias
parameters:
- in: path
type: string
@ -124,6 +126,7 @@ paths:
Remove a mapping of room alias to room ID.
Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
operationId: deleteRoomAlias
security:
- accessToken: []
parameters:

1
api/client-server/event_context.yaml
View file

@ -34,6 +34,7 @@ paths:
This API returns a number of events that happened just before and
after the specified event. This allows clients to get the context
surrounding an event.
operationId: getEventContext
security:
- accessToken: []
parameters:

2
api/client-server/filter.yaml
View file

@ -33,6 +33,7 @@ paths:
Uploads a new filter definition to the homeserver.
Returns a filter ID that may be used in future requests to
restrict which events are returned to the client.
operationId: defineFilter
security:
- accessToken: []
parameters:
@ -96,6 +97,7 @@ paths:
"/user/{userId}/filter/{filterId}":
get:
summary: Download a filter
operationId: getFilter
security:
- accessToken: []
parameters:

1
api/client-server/inviting.yaml
View file

@ -51,6 +51,7 @@ paths:
``m.room.member`` event to the room.
.. _third party invites section: `invite-by-third-party-id-endpoint`_
operationId: inviteUser
security:
- accessToken: []
parameters:

2
api/client-server/joining.yaml
View file

@ -44,6 +44,7 @@ paths:
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoomById
security:
- accessToken: []
parameters:
@ -132,6 +133,7 @@ paths:
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoom
security:
- accessToken: []
parameters:

4
api/client-server/keys.yaml
View file

@ -32,6 +32,7 @@ paths:
summary: Upload end-to-end encryption keys.
description: |-
Publishes end-to-end encryption keys for the device.
operationId: uploadKeys
security:
- accessToken: []
parameters:
@ -100,6 +101,7 @@ paths:
summary: Download device identity keys.
description: |-
Returns the current devices and identity keys for the given users.
operationId: queryKeys
security:
- accessToken: []
parameters:
@ -208,6 +210,7 @@ paths:
summary: Claim one-time encryption keys.
description: |-
Claims one-time keys for use in pre-key messages.
operationId: claimKeys
security:
- accessToken: []
parameters:
@ -293,6 +296,7 @@ paths:
membership state ``join``); *and*
* added new device identity keys or removed an existing device with
identity keys, between ``from`` and ``to``.
operationId: getKeysChanges
security:
- accessToken: []
parameters:

1
api/client-server/kicking.yaml
View file

@ -34,6 +34,7 @@ paths:
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
operationId: kick
security:
- accessToken: []
parameters:

2
api/client-server/leaving.yaml
View file

@ -42,6 +42,7 @@ paths:
The user will still be allowed to retrieve history from the room which
they were previously allowed to see.
operationId: leaveRoom
security:
- accessToken: []
parameters:
@ -79,6 +80,7 @@ paths:
If the user is currently joined to the room, they will implicitly leave
the room as part of this API call.
operationId: forgetRoom
security:
- accessToken: []
parameters:

2
api/client-server/list_public_rooms.yaml
View file

@ -33,6 +33,7 @@ paths:
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
operationId: getPublicRooms
parameters:
- in: query
name: limit
@ -158,6 +159,7 @@ paths:
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
operationId: queryPublicRooms
security:
- accessToken: []
parameters:

1
api/client-server/login.yaml
View file

@ -41,6 +41,7 @@ paths:
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
operationId: login
parameters:
- in: body
name: body

1
api/client-server/logout.yaml
View file

@ -33,6 +33,7 @@ paths:
description: |-
Invalidates an existing access token, so that it can no longer be used for
authorization.
operationId: logout
security:
- accessToken: []
responses:

1
api/client-server/message_pagination.yaml
View file

@ -33,6 +33,7 @@ paths:
description: |-
This API returns a list of message and state events for a room. It uses
pagination query parameters to paginate history in the room.
operationId: getRoomEvents
security:
- accessToken: []
parameters:

1
api/client-server/notifications.yaml
View file

@ -34,6 +34,7 @@ paths:
description: |-
This API is used to paginate through the list of events that the
user has been, or would have been notified about.
operationId: getNotifications
security:
- accessToken: []
parameters:

3
api/client-server/old_sync.yaml
View file

@ -38,6 +38,7 @@ paths:
should instead call the |/sync|_ API with a ``since`` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: getEvents
security:
- accessToken: []
parameters:
@ -114,6 +115,7 @@ paths:
should instead call the |/sync|_ API with no ``since`` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: initialSync
security:
- accessToken: []
parameters:
@ -406,6 +408,7 @@ paths:
This endpoint was deprecated in r0 of this specification. Clients
should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
operationId: getOneEvent
security:
- accessToken: []
parameters:

1
api/client-server/peeking_events.yaml
View file

@ -41,6 +41,7 @@ paths:
Note that the normal ``/events`` endpoint has been deprecated. This
API will also be deprecated at some point, but its replacement is not
yet known.
operationId: peekEvents
security:
- accessToken: []
parameters:

4
api/client-server/presence.yaml
View file

@ -35,6 +35,7 @@ paths:
the activity time is updated to reflect that activity; the client does
not need to specify the ``last_active_ago`` field. You cannot set the
presence state of another user.
operationId: setPresence
security:
- accessToken: []
parameters:
@ -81,6 +82,7 @@ paths:
summary: Get this user's presence state.
description: |-
Get the given user's presence state.
operationId: getPresence
parameters:
- in: path
type: string
@ -126,6 +128,7 @@ paths:
summary: Add or remove users from this presence list.
description: |-
Adds or removes users from this presence list.
operationId: modifyPresenceList
security:
- accessToken: []
parameters:
@ -180,6 +183,7 @@ paths:
summary: Get presence events for this presence list.
description: |-
Retrieve a list of presence events for every user on this list.
operationId: getPresenceForList
parameters:
- in: path
type: string

5
api/client-server/profile.yaml
View file

@ -33,6 +33,7 @@ paths:
description: |-
This API sets the given user's display name. You must have permission to
set this user's display name, e.g. you need to have their ``access_token``.
operationId: setDisplayName
security:
- accessToken: []
parameters:
@ -75,6 +76,7 @@ paths:
Get the user's display name. This API may be used to fetch the user's
own displayname or to query the name of other users; either locally or
on remote homeservers.
operationId: getDisplayName
parameters:
- in: path
type: string
@ -105,6 +107,7 @@ paths:
description: |-
This API sets the given user's avatar URL. You must have permission to
set this user's avatar URL, e.g. you need to have their ``access_token``.
operationId: setAvatarUrl
security:
- accessToken: []
parameters:
@ -147,6 +150,7 @@ paths:
Get the user's avatar URL. This API may be used to fetch the user's
own avatar URL or to query the URL of other users; either locally or
on remote homeservers.
operationId: getAvatarUrl
parameters:
- in: path
type: string
@ -179,6 +183,7 @@ paths:
to fetch the user's own profile information or other users; either
locally or on remote homeservers. This API may return keys which are not
limited to ``displayname`` or ``avatar_url``.
operationId: getUserProfile
parameters:
- in: path
type: string

2
api/client-server/pusher.yaml
View file

@ -32,6 +32,7 @@ paths:
summary: Gets the current pushers for the authenticated user
description: |-
Gets all currently active pushers for the authenticated user
operationId: getPushers
security:
- accessToken: []
responses:
@ -123,6 +124,7 @@ paths:
This endpoint allows the creation, modification and deletion of `pushers`_
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
operationId: postPusher
security:
- accessToken: []
parameters:

8
api/client-server/pushrules.yaml
View file

@ -35,6 +35,7 @@ paths:
the rulesets by suffixing a ``scope`` to this path e.g.
``/pushrules/global/``. This will return a subset of this data under the
specified key e.g. the ``global`` key.
operationId: getPushRules
security:
- accessToken: []
responses:
@ -247,6 +248,7 @@ paths:
summary: Retrieve a push rule.
description: |-
Retrieve a single specified push rule.
operationId: getPushRule
security:
- accessToken: []
parameters:
@ -299,6 +301,7 @@ paths:
summary: Delete a push rule.
description: |-
This endpoint removes the push rule defined in the path.
operationId: deletePushRule
security:
- accessToken: []
parameters:
@ -340,6 +343,7 @@ paths:
This endpoint allows the creation, modification and deletion of pushers
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
operationId: setPushRule
security:
- accessToken: []
parameters:
@ -446,6 +450,7 @@ paths:
summary: "Get whether a push rule is enabled"
description:
This endpoint gets whether the specified push rule is enabled.
operationId: isPushRuleEnabled
security:
- accessToken: []
parameters:
@ -490,6 +495,7 @@ paths:
summary: "Enable or disable a push rule."
description: |-
This endpoint allows clients to enable or disable the specified push rule.
operationId: setPushRuleEnabled
security:
- accessToken: []
parameters:
@ -545,6 +551,7 @@ paths:
summary: "The actions for a push rule"
description:
This endpoint get the actions for the specified push rule.
operationId: getPushRuleActions
security:
- accessToken: []
parameters:
@ -592,6 +599,7 @@ paths:
description: |-
This endpoint allows clients to change the actions of a push rule.
This can be used to change the actions of builtin rules.
operationId: setPushRuleActions
security:
- accessToken: []
parameters:

1
api/client-server/receipts.yaml
View file

@ -33,6 +33,7 @@ paths:
description: |-
This API updates the marker for the given receipt type to the event ID
specified.
operationId: postReceipt
security:
- accessToken: []
parameters:

1
api/client-server/redaction.yaml
View file

@ -39,6 +39,7 @@ paths:
Users may redact their own events, and any user with a power level
greater than or equal to the `redact` power level of the room may
redact events there.
operationId: redactEvent
security:
- accessToken: []
parameters:

5
api/client-server/registration.yaml
View file

@ -49,6 +49,7 @@ paths:
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
operationId: register
parameters:
- in: query
name: kind
@ -178,6 +179,7 @@ paths:
this API takes JSON objects, though the Identity Server API takes
``x-www-form-urlencoded`` parameters. See the Identity Server API for
further information.
operationId: requestTokenToRegister
parameters:
- in: body
name: body
@ -244,6 +246,7 @@ paths:
valid access token is provided.
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
@ -295,6 +298,7 @@ paths:
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPassword
responses:
200:
description: An email was sent to the given address
@ -314,6 +318,7 @@ paths:
valid access token is provided.
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body

1
api/client-server/room_initial_sync.yaml
View file

@ -24,6 +24,7 @@ paths:
direct replacement; the relevant information is returned by the
|/sync|_ API. See the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: roomInitialSync
security:
- accessToken: []
parameters:

1
api/client-server/room_send.yaml
View file

@ -38,6 +38,7 @@ paths:
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the m. event specification.
operationId: sendMessage
security:
- accessToken: []
parameters:

2
api/client-server/room_state.yaml
View file

@ -42,6 +42,7 @@ paths:
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
operationId: setRoomStateWithKey
security:
- accessToken: []
parameters:
@ -104,6 +105,7 @@ paths:
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
operationId: setRoomState
security:
- accessToken: []
parameters:

4
api/client-server/rooms.yaml
View file

@ -35,6 +35,7 @@ paths:
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
taken from the state of the room when they left.
operationId: getRoomStateWithKey
security:
- accessToken: []
parameters:
@ -82,6 +83,7 @@ paths:
taken from the state of the room when they left.
This looks up the state event with the empty state key.
operationId: getRoomStateByType
security:
- accessToken: []
parameters:
@ -118,6 +120,7 @@ paths:
summary: Get all state events in the current state of a room.
description: |-
Get the state events for the current state of a room.
operationId: getRoomState
security:
- accessToken: []
parameters:
@ -234,6 +237,7 @@ paths:
summary: Get the m.room.member events for the room.
description:
Get the list of members for this room.
operationId: getRoomMembers
parameters:
- in: path
type: string

1
api/client-server/search.yaml
View file

@ -32,6 +32,7 @@ paths:
summary: Perform a server-side search.
description: |-
Performs a full text search across different categories.
operationId: search
security:
- accessToken: []
parameters:

1
api/client-server/sync.yaml
View file

@ -34,6 +34,7 @@ paths:
Clients use this API when they first log in to get an initial snapshot
of the state on the server, and then continue to call this API to get
incremental deltas to the state, and to receive new messages.
operationId: sync
security:
- accessToken: []
parameters:

3
api/client-server/tags.yaml
View file

@ -32,6 +32,7 @@ paths:
summary: List the tags for a room.
description: |-
List the tags set by a user on a room.
operationId: getRoomTags
security:
- accessToken: []
parameters:
@ -74,6 +75,7 @@ paths:
summary: Add a tag to a room.
description: |-
Add a tag to the room.
operationId: setRoomTag
security:
- accessToken: []
parameters:
@ -123,6 +125,7 @@ paths:
summary: Remove a tag from the room.
description: |-
Remove a tag from the room.
operationId: deleteRoomTag
security:
- accessToken: []
parameters:

1
api/client-server/third_party_membership.yaml
View file

@ -75,6 +75,7 @@ paths:
append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_
operationId: inviteBy3PID
security:
- accessToken: []
parameters:

1
api/client-server/to_device.yaml
View file

@ -34,6 +34,7 @@ paths:
description: |-
This endpoint is used to send send-to-device events to a set of
client devices.
operationId: sendToDevice
security:
- accessToken: []
parameters:

1
api/client-server/typing.yaml
View file

@ -35,6 +35,7 @@ paths:
milliseconds where N is the value specified in the ``timeout`` key.
Alternatively, if ``typing`` is ``false``, it tells the server that the
user has stopped typing.
operationId: setTyping
security:
- accessToken: []
parameters:

1
api/client-server/versions.yaml
View file

@ -33,6 +33,7 @@ paths:
Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
operationId: getVersions
responses:
200:
description: The versions supported by the server.

1
api/client-server/voip.yaml
View file

@ -33,6 +33,7 @@ paths:
description: |-
This API provides credentials for the client to use when initiating
calls.
operationId: getTurnServer
security:
- accessToken: []
responses:

1
api/identity/lookup.yaml
View file

@ -27,6 +27,7 @@ paths:
get:
summary: Look up the Matrix user ID for a 3pid.
description: Look up the Matrix user ID for a 3pid.
operationId: lookupUser
parameters:
- in: query
type: string

3
api/identity/pubkey.yaml
View file

@ -28,6 +28,7 @@ paths:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
operationId: getPubKey
parameters:
- in: path
type: string
@ -56,6 +57,7 @@ paths:
summary: Check whether a long-term public key is valid.
description: |-
Check whether a long-term public key is valid.
operationId: isPubKeyValid
parameters:
- in: query
type: string
@ -83,6 +85,7 @@ paths:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValid
parameters:
- in: query
type: string

2
api/push-gateway/push_notifier.yaml
View file

@ -46,7 +46,7 @@ paths:
Notifications are sent to the URL configured when the pusher is
created. This means that the HTTP path may be different depending on the
push gateway.
operationId: notify
parameters:
- in: body
name: notification