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

Manual fixes to API files

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-05-09 16:24:43 +02:00
parent 10603b43c3
commit c3a4f5b109
No known key found for this signature in database
GPG key ID: 29A48C1F03620416
33 changed files with 226 additions and 137 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
data/api/client-server/appservice_room_directory.yaml
View file

@ -67,6 +67,7 @@ paths:
- visibility
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
"200":
@ -94,4 +95,6 @@ servers:
default: /_matrix/client/v3
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

93
data/api/client-server/content-repo.yaml
View file

@ -38,12 +38,7 @@ paths:
type: string
requestBody:
content:
application/json:
schema:
type: string
example: <bytes>
format: byte
"*/*":
application/octet-stream:
schema:
type: string
example: <bytes>
@ -146,12 +141,7 @@ paths:
type: string
requestBody:
content:
application/json:
schema:
type: string
example: <bytes>
format: byte
"*/*":
application/octet-stream:
schema:
type: string
example: <bytes>
@ -168,9 +158,6 @@ paths:
examples:
response:
value: {}
"*/*":
schema:
type: object
"403":
description: |-
The user does not have permission to upload the content. Some reasons for this error include:
@ -192,9 +179,6 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "Cannot upload this content"
}
"*/*":
schema:
$ref: definitions/errors/error.yaml
"409":
description: |-
The endpoint was called with a media ID that already has content. A
@ -210,9 +194,6 @@ paths:
"errcode": "M_CANNOT_OVERWRITE_MEDIA",
"error": "Media already uploaded"
}
"*/*":
schema:
$ref: definitions/errors/error.yaml
"413":
description: The uploaded content is too large for the server.
content:
@ -225,18 +206,12 @@ paths:
"errcode": "M_TOO_LARGE",
"error": "Cannot upload files larger than 100mb"
}
"*/*":
schema:
$ref: definitions/errors/error.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
"*/*":
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Media
/media/v1/create:
@ -266,6 +241,8 @@ paths:
x-addedInMatrixVersion: "1.7"
security:
- accessToken: []
# empty json object
parameters: []
responses:
"200":
description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
@ -371,24 +348,23 @@ paths:
schema:
type: string
content:
"*/*":
application/octet-stream:
schema:
type: string
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
format: binary
"429":
description: This request was rate-limited.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
"502":
description: The content is too large for the server to serve.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/error.yaml
application/json:
examples:
response:
value: {
@ -400,10 +376,9 @@ paths:
The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/error.yaml
application/json:
examples:
response:
value: {
@ -485,24 +460,24 @@ paths:
schema:
type: string
content:
"*/*":
application/octet-stream:
schema:
type: string
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
format: binary
"429":
description: This request was rate-limited.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
"502":
description: The content is too large for the server to serve.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/error.yaml
application/json:
examples:
response:
value: {
@ -514,10 +489,9 @@ paths:
The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
content:
"*/*":
application/json:
schema:
$ref: definitions/errors/error.yaml
application/json:
examples:
response:
value: {
@ -620,11 +594,13 @@ paths:
image/jpeg:
schema:
type: string
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
format: binary
image/png:
schema:
type: string
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
format: binary
"400":
@ -633,13 +609,9 @@ paths:
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
content:
image/jpeg:
schema:
$ref: definitions/errors/error.yaml
image/png:
schema:
$ref: definitions/errors/error.yaml
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
@ -649,13 +621,9 @@ paths:
"413":
description: The local content is too large for the server to thumbnail.
content:
image/jpeg:
schema:
$ref: definitions/errors/error.yaml
image/png:
schema:
$ref: definitions/errors/error.yaml
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
@ -665,22 +633,15 @@ paths:
"429":
description: This request was rate-limited.
content:
image/jpeg:
schema:
$ref: definitions/errors/rate_limited.yaml
image/png:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
"502":
description: The remote content is too large for the server to thumbnail.
content:
image/jpeg:
schema:
$ref: definitions/errors/error.yaml
image/png:
schema:
$ref: definitions/errors/error.yaml
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
@ -692,13 +653,9 @@ paths:
The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
content:
image/jpeg:
schema:
$ref: definitions/errors/error.yaml
image/png:
schema:
$ref: definitions/errors/error.yaml
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {

6
data/api/client-server/definitions/push_rule.yaml
View file

@ -17,9 +17,9 @@ type: object
properties:
actions:
items:
type:
- object
- string
oneOf:
- type: object
- type: string
type: array
description: |-
The actions to perform when this rule is matched.

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

@ -124,7 +124,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}

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

@ -16,6 +16,8 @@ info:
title: Matrix Client-Server Room Joining API
version: 1.0.0
paths:
# With an extra " " to disambiguate from the 3pid invite endpoint
# The extra space makes it sort first for what I'm sure is a good reason.
"/rooms/{roomId}/invite ":
post:
summary: Invite a user to participate in a particular room.

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

@ -143,8 +143,6 @@ paths:
example:
- matrix.org
- elsewhere.ca
style: form
explode: false
schema:
type: array
items:

11
data/api/client-server/keys.yaml
View file

@ -38,6 +38,10 @@ paths:
allOf:
- $ref: definitions/device_keys.yaml
one_time_keys:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
type: object
title: OneTimeKeys
description: |-
@ -61,6 +65,8 @@ paths:
ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
fallback_keys:
x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here - see above.
type: object
title: OneTimeKeys
description: |-
@ -346,6 +352,11 @@ paths:
additionalProperties:
type: object
additionalProperties:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will read the link provided in the description
# and figure it out from the other endpoints/example.
# See also one_time_key parameter for /keys/upload above.
type: object
title: OneTimeKeys
example:

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

@ -55,8 +55,6 @@ paths:
example:
- matrix.org
- elsewhere.ca
style: form
explode: false
schema:
type: array
items:

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

@ -16,6 +16,8 @@ info:
title: Matrix Client-Server Sync Guest API
version: 1.0.0
paths:
# With an extra " " to disambiguate from the getEvents endpoint
# The extra space makes it sort first for what I'm sure is a good reason.
"/events ":
get:
summary: Listen on the event stream of a particular room.

5
data/api/client-server/presence.yaml
View file

@ -65,7 +65,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}
@ -113,8 +113,7 @@ paths:
by this user.
status_msg:
description: The state message for this user if one was set.
nullable: true
type: string
type: ["string", "null"]
currently_active:
type: boolean
description: Whether the user is currently active

4
data/api/client-server/profile.yaml
View file

@ -53,7 +53,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}
@ -139,7 +139,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}

3
data/api/client-server/pusher.yaml
View file

@ -174,8 +174,7 @@ paths:
The kind of pusher to configure. `"http"` makes a pusher that
sends HTTP pokes. `"email"` makes a pusher that emails the
user with unread notifications. `null` deletes the pusher.
nullable: true
type: string
type: ["string", "null"]
app_id:
type: string
description: |-

4
data/api/client-server/pushrules.yaml
View file

@ -350,7 +350,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}
@ -487,7 +487,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}

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

@ -89,7 +89,7 @@ paths:
application/json:
schema:
type: object
maxProperties: 0
maxProperties: 0 # empty json object
examples:
response:
value: {}

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

@ -66,6 +66,8 @@ paths:
name: kind
required: false
description: The kind of account to register. Defaults to `user`.
# swagger-UI overrides the default with the example, so better make the
# example the default.
example: user
schema:
type: string

8
data/api/client-server/relations.yaml
View file

@ -97,6 +97,8 @@ paths:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
"200":
description: |-
The paginated child events which point to the parent. If no events are
@ -161,6 +163,7 @@ paths:
}
tags:
- Event relationships
# The same as above, with added `/{relType}`
"/rooms/{roomId}/relations/{eventId}/{relType}":
get:
summary: Get the child events for a given parent event, with a given `relType`.
@ -251,6 +254,8 @@ paths:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
"200":
description: |-
The paginated child events which point to the parent. If no events are
@ -317,6 +322,7 @@ paths:
}
tags:
- Event relationships
# The same as above, with added `/{eventType}`
"/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
get:
summary: Get the child events for a given parent event, with a given `relType`
@ -419,6 +425,8 @@ paths:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
"200":
description: |-
The paginated child events which point to the parent. If no events are

3
data/api/client-server/rooms.yaml
View file

@ -200,6 +200,9 @@ paths:
example: YWxsCgpOb25lLDM1ODcwOA
schema:
type: string
# XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
# filter might be a better alternative.
# See https://github.com/matrix-org/matrix-doc/issues/1337
- in: query
name: membership
description: |-

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

@ -70,7 +70,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
examples:
response:
value: {}

1
data/api/identity/v2_terms.yaml
View file

@ -52,6 +52,7 @@ paths:
might be and could be "alpha", semantically versioned, or arbitrary.
required:
- version
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy

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

@ -202,7 +202,7 @@ paths:
content:
application/json:
schema:
type: object
type: object # empty json object
properties:
rejected:
type: array

2
data/api/server-server/backfill.yaml
View file

@ -40,8 +40,6 @@ paths:
required: true
example:
- $abc123:matrix.org
style: form
explode: false
schema:
type: array
items:

58
data/api/server-server/definitions/unsigned_pdu_base.yaml
View file

@ -56,20 +56,21 @@ properties:
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
depth:
type: integer
description: |-
@ -91,20 +92,21 @@ properties:
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
redacts:
type: string
description: For redaction events, the ID of the event being redacted.

16
data/api/server-server/invites-v1.yaml
View file

@ -75,6 +75,22 @@ paths:
example:
$ref: ../../event-schemas/examples/invite_room_state.json
type: object
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
required: true
responses:
"200":

19
data/api/server-server/invites-v2.yaml
View file

@ -78,6 +78,25 @@ paths:
required:
- room_version
- event
example: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
}
required: true
responses:
"200":

20
data/api/server-server/joins-v1.yaml
View file

@ -49,8 +49,6 @@ paths:
example:
- "1"
- "2"
style: form
explode: false
schema:
type: array
items:
@ -321,6 +319,18 @@ paths:
- origin_server_ts
- type
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
required: true
responses:
"200":
@ -356,9 +366,6 @@ paths:
description: |-
The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
state:
type: array
description: |-
@ -372,9 +379,6 @@ paths:
description: |-
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
required:
- auth_chain
- state

19
data/api/server-server/joins-v2.yaml
View file

@ -17,6 +17,7 @@ info:
title: Matrix Federation Join Room API
version: 1.0.0
paths:
# Note: there is no v2 of make_join (yet)
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
@ -138,6 +139,18 @@ paths:
- origin_server_ts
- type
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
required: true
responses:
"200":
@ -171,9 +184,6 @@ paths:
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
@ -190,9 +200,6 @@ paths:
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": permit omission of membership events.
event:

2
data/api/server-server/keys_query.yaml
View file

@ -88,7 +88,7 @@ paths:
given.
additionalProperties:
type: object
name: ServerName
title: ServerName
description: The server names to query.
additionalProperties:
type: object

17
data/api/server-server/knocks.yaml
View file

@ -44,12 +44,10 @@ paths:
- in: query
name: ver
description: The room versions the sending server has support for.
required: true
required: true # knocking was supported in v7
example:
- "1"
- "7"
style: form
explode: false
schema:
type: array
items:
@ -121,7 +119,7 @@ paths:
- content
- sender
required:
- room_version
- room_version # knocking was added in v7
- event
examples:
response:
@ -273,6 +271,17 @@ paths:
- origin_server_ts
- type
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "knock"
}
}
required: true
responses:
"200":

11
data/api/server-server/leaving-v1.yaml
View file

@ -222,6 +222,17 @@ paths:
- type
- depth
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
}
required: true
responses:
"200":

12
data/api/server-server/leaving-v2.yaml
View file

@ -17,6 +17,7 @@ info:
title: Matrix Federation Leave Room API
version: 1.0.0
paths:
# Note: there is no v2 of make_leave (yet)
"/send_leave/{roomId}/{eventId}":
put:
summary: Submit a signed leave event to a resident server
@ -107,6 +108,17 @@ paths:
- type
- depth
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
}
required: true
responses:
"200":

1
data/api/server-server/public_rooms.yaml
View file

@ -159,6 +159,7 @@ paths:
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
- type: object
properties:
# Override description of join_rule
join_rule:
type: string
description: |-

24
data/api/server-server/third_party_invite.yaml
View file

@ -151,6 +151,27 @@ paths:
- sender
- state_key
- content
example: {
"type": "m.room.member",
"room_id": "!abc123:matrix.org",
"sender": "@joe:matrix.org",
"state_key": "@someone:example.org",
"content": {
"membership": "invite",
"third_party_invite": {
"display_name": "alice",
"signed": {
"mxid": "@alice:localhost",
"token": "abc123",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}
}
}
}
description: A partial `m.room.member` event
required: true
responses:
@ -225,6 +246,8 @@ paths:
type: string
description: The user ID that sent the invite.
example: "@bob:matrix.org"
# TODO (TravisR): Make this reusable when doing IS spec changes
# also make sure it isn't lying about anything, like the key version
signed:
type: object
title: Identity Server Signatures
@ -240,6 +263,7 @@ paths:
example: "@alice:matrix.org"
token:
type: string
# TODO: What is this actually?
description: A token.
example: Hello World
signatures:

3
data/api/server-server/user_keys.yaml
View file

@ -63,10 +63,13 @@ paths:
See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
the Key Object format.
# User
additionalProperties:
type: object
# Device
additionalProperties:
type: object
# Key
additionalProperties:
type: object
title: KeyObject