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

Format examples as raw objects

Browse source 
According the the openapi spec, examples for responses and schemas should be
raw objects rather than being json strings. (It's unclear what non-json
examples should look like...).

The swagger UI used to support json strings, but no longer does. In short,
let's turn the json strings into their raw formats.
This commit is contained in:
Richard van der Hoff 2017-09-26 17:53:28 +01:00
parent 0795f3667e
commit 820704a16a
44 changed files with 183 additions and 290 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -45,8 +45,7 @@ paths:
description: A list of events description: A list of events
schema: schema:
type: object type: object
example: |- example: {
{
"events": [ "events": [
{ {
"age": 32, "age": 32,
@ -87,8 +86,8 @@ paths:
200: 200:
description: The transaction was processed successfully. description: The transaction was processed successfully.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
@ -117,8 +116,8 @@ paths:
information about the room such as its name and topic can be set information about the room such as its name and topic can be set
before responding. before responding.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
401: 401:
@ -126,8 +125,7 @@ paths:
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: examples:
application/json: |- application/json: {
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
schema: schema:
@ -136,8 +134,7 @@ paths:
description: |- description: |-
The credentials supplied by the homeserver were rejected. The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_FORBIDDEN" "errcode": "M_FORBIDDEN"
} }
schema: schema:
@ -147,8 +144,7 @@ paths:
The application service indicates that this room alias does not exist. The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: examples:
application/json: |- application/json: {
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema: schema:
@ -175,8 +171,8 @@ paths:
The application service indicates that this user exists. The application The application service indicates that this user exists. The application
service MUST create the user using the client-server API. service MUST create the user using the client-server API.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
401: 401:
@ -184,8 +180,7 @@ paths:
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: examples:
application/json: |- application/json: {
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
schema: schema:
@ -194,8 +189,7 @@ paths:
description: |- description: |-
The credentials supplied by the homeserver were rejected. The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_FORBIDDEN" "errcode": "M_FORBIDDEN"
} }
schema: schema:
@ -205,8 +199,7 @@ paths:
The application service indicates that this user does not exist. The application service indicates that this user does not exist.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: examples:
application/json: |- application/json: {
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema: schema:

21
api/check_examples.py
View file

@ -45,15 +45,8 @@ except ImportError as e:
def check_parameter(filepath, request, parameter): def check_parameter(filepath, request, parameter):
schema = parameter.get("schema") schema = parameter.get("schema")
example = None example = schema.get('example')
try:
example_json = schema.get('example')
if example_json and not schema.get("format") == "byte":
example = json.loads(example_json)
except Exception as e:
raise ValueError("Error parsing JSON example request for %r" % (
request
), e)
fileurl = "file://" + os.path.abspath(filepath) fileurl = "file://" + os.path.abspath(filepath)
if example and schema: if example and schema:
try: try:
@ -72,15 +65,7 @@ def check_parameter(filepath, request, parameter):
def check_response(filepath, request, code, response): def check_response(filepath, request, code, response):
example = None example = response.get('examples', {}).get('application/json')
try:
example_json = response.get('examples', {}).get('application/json')
if example_json:
example = json.loads(example_json)
except Exception as e:
raise ValueError("Error parsing JSON example response for %r %r" % (
request, code
), e)
schema = response.get('schema') schema = response.get('schema')
fileurl = "file://" + os.path.abspath(filepath) fileurl = "file://" + os.path.abspath(filepath)
if example and schema: if example and schema:

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

@ -60,8 +60,8 @@ paths:
The content of the account_data The content of the account_data
schema: schema:
type: object type: object
example: |- example: {
{"custom_account_data_key": "custom_config_value"} "custom_account_data_key": "custom_config_value"}
responses: responses:
200: 200:
description: description:
@ -108,8 +108,8 @@ paths:
The content of the account_data The content of the account_data
schema: schema:
type: object type: object
example: |- example: {
{"custom_account_data_key": "custom_account_data_value"} "custom_account_data_key": "custom_account_data_value"}
responses: responses:
200: 200:
description: description:

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

@ -49,8 +49,7 @@ paths:
200: 200:
description: The lookup was successful. description: The lookup was successful.
examples: examples:
application/json: |- application/json: {
{
"user_id": "@peter:rabbit.rocks", "user_id": "@peter:rabbit.rocks",
"devices": { "devices": {
"teapot": { "teapot": {

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

@ -45,8 +45,7 @@ paths:
200: 200:
description: The lookup was successful. description: The lookup was successful.
examples: examples:
application/json: |- application/json: {
{
"threepids": [ "threepids": [
{ {
"medium": "email", "medium": "email",
@ -106,8 +105,7 @@ paths:
server. Default: ``false``. server. Default: ``false``.
x-example: true x-example: true
required: ["three_pid_creds"] required: ["three_pid_creds"]
example: |- example: {
{
"three_pid_creds": { "three_pid_creds": {
"id_server": "matrix.org", "id_server": "matrix.org",
"sid": "abc123987", "sid": "abc123987",
@ -119,14 +117,13 @@ paths:
200: 200:
description: The addition was successful. description: The addition was successful.
examples: examples:
application/json: "{}" application/json: {}
schema: schema:
type: object type: object
403: 403:
description: The credentials could not be verified with the identity server. description: The credentials could not be verified with the identity server.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_THREEPID_AUTH_FAILED", "errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server." "error": "The third party credentials could not be verified by the identity server."
} }

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

@ -50,8 +50,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"reason": "Telling unfunny jokes", "reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org" "user_id": "@cheeky_monkey:matrix.org"
} }
@ -67,8 +66,8 @@ paths:
200: 200:
description: The user has been kicked and banned from the room. description: The user has been kicked and banned from the room.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
403: 403:
@ -78,8 +77,7 @@ paths:
- The banner is not currently in the room. - The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room. - The banner's power level is insufficient to ban users from the room.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room." "error": "You do not have a high enough power level to ban from this room."
} }
@ -107,8 +105,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"user_id": "@cheeky_monkey:matrix.org" "user_id": "@cheeky_monkey:matrix.org"
} }
properties: properties:
@ -120,8 +117,8 @@ paths:
200: 200:
description: The user has been unbanned from the room. description: The user has been unbanned from the room.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
403: 403:
@ -130,8 +127,7 @@ paths:
- The unbanner's power level is insufficient to unban users from the room. - The unbanner's power level is insufficient to unban users from the room.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room." "error": "You do not have a high enough power level to unban from this room."
} }

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

@ -57,8 +57,7 @@ paths:
type: string type: string
description: "The MXC URI to the uploaded content." description: "The MXC URI to the uploaded content."
examples: examples:
"application/json": |- application/json: {
{
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
} }
tags: tags:

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

@ -54,8 +54,7 @@ paths:
description: The desired room configuration. description: The desired room configuration.
schema: schema:
type: object type: object
example: |- example: {
{
"preset": "public_chat", "preset": "public_chat",
"room_alias_name": "thepub", "room_alias_name": "thepub",
"name": "The Grand Duke Pub", "name": "The Grand Duke Pub",
@ -188,8 +187,7 @@ paths:
description: |- description: |-
The created room's ID. The created room's ID.
examples: examples:
application/json: |- application/json: {
{
"room_id": "!sefiuhWgwghwWgh:example.com" "room_id": "!sefiuhWgwghwWgh:example.com"
} }
400: 400:

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

@ -49,8 +49,7 @@ paths:
allOf: allOf:
- $ref: "definitions/client_device.yaml" - $ref: "definitions/client_device.yaml"
examples: examples:
application/json: |- application/json: {
{
"devices": [ "devices": [
{ {
"device_id": "QBUAZIFURK", "device_id": "QBUAZIFURK",
@ -84,8 +83,7 @@ paths:
allOf: allOf:
- $ref: "definitions/client_device.yaml" - $ref: "definitions/client_device.yaml"
examples: examples:
application/json: |- application/json: {
{
"device_id": "QBUAZIFURK", "device_id": "QBUAZIFURK",
"display_name": "android", "display_name": "android",
"last_seen_ip": "1.2.3.4", "last_seen_ip": "1.2.3.4",
@ -125,8 +123,8 @@ paths:
200: 200:
description: The device was successfully updated. description: The device was successfully updated.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
404: 404:
@ -166,8 +164,8 @@ paths:
schema: schema:
type: object type: object
examples: examples:
application/json: |- application/json: {
{} }
401: 401:
description: |- description: |-
The homeserver requires additional authentication information. The homeserver requires additional authentication information.

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

@ -49,23 +49,21 @@ paths:
room_id: room_id:
type: string type: string
description: The room ID to set. description: The room ID to set.
example: |- example: {
{
"room_id": "!abnjk1jdasj98:capuchins.com" "room_id": "!abnjk1jdasj98:capuchins.com"
} }
responses: responses:
200: 200:
description: The mapping was created. description: The mapping was created.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
409: 409:
description: A room alias with that name already exists. description: A room alias with that name already exists.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_UNKNOWN", "errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists." "error": "Room alias #monkeys:matrix.org already exists."
} }
@ -103,8 +101,7 @@ paths:
type: string type: string
description: A server which is aware of this room alias. description: A server which is aware of this room alias.
examples: examples:
application/json: |- application/json: {
{
"room_id": "!abnjk1jdasj98:capuchins.com", "room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [ "servers": [
"capuchins.com", "capuchins.com",
@ -115,8 +112,7 @@ paths:
404: 404:
description: There is no mapped room ID for this room alias. description: There is no mapped room ID for this room alias.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_NOT_FOUND", "errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found." "error": "Room alias #monkeys:matrix.org not found."
} }
@ -141,8 +137,8 @@ paths:
200: 200:
description: The mapping was deleted. description: The mapping was deleted.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
tags: tags:

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

@ -99,8 +99,7 @@ paths:
allOf: allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml" - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples: examples:
application/json: |- application/json: {
{
"end": "t29-57_2_0_2", "end": "t29-57_2_0_2",
"events_after": [ "events_after": [
{ {

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

@ -52,8 +52,7 @@ paths:
type: object type: object
allOf: allOf:
- $ref: "definitions/sync_filter.yaml" - $ref: "definitions/sync_filter.yaml"
example: |- example: {
{
"room": { "room": {
"state": { "state": {
"types": ["m.room.*"], "types": ["m.room.*"],
@ -82,8 +81,7 @@ paths:
200: 200:
description: The filter was created. description: The filter was created.
examples: examples:
application/json: |- application/json: {
{
"filter_id": "66696p746572" "filter_id": "66696p746572"
} }
schema: schema:
@ -120,8 +118,7 @@ paths:
description: |- description: |-
"The filter defintion" "The filter defintion"
examples: examples:
application/json: |- application/json: {
{
"room": { "room": {
"state": { "state": {
"types": ["m.room.*"], "types": ["m.room.*"],

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

@ -65,8 +65,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"user_id": "@cheeky_monkey:matrix.org" "user_id": "@cheeky_monkey:matrix.org"
} }
properties: properties:
@ -78,8 +77,8 @@ paths:
200: 200:
description: The user has been invited to join the room. description: The user has been invited to join the room.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
403: 403:
@ -91,8 +90,8 @@ paths:
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
examples: examples:
application/json: |- application/json: {
{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:

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

@ -57,8 +57,7 @@ paths:
name: third_party_signed name: third_party_signed
schema: schema:
type: object type: object
example: |- example: {
{
"third_party_signed": { "third_party_signed": {
"sender": "@cat:the.hat", "sender": "@cat:the.hat",
"mxid": "@green:eggs.ham", "mxid": "@green:eggs.ham",
@ -97,8 +96,8 @@ paths:
The joined room ID must be returned in the ``room_id`` field. The joined room ID must be returned in the ``room_id`` field.
examples: examples:
application/json: |- application/json: {
{"room_id": "!d41d8cd:matrix.org"} "room_id": "!d41d8cd:matrix.org"}
schema: schema:
type: object type: object
403: 403:
@ -108,8 +107,8 @@ paths:
- The room is invite-only and the user was not invited. - The room is invite-only and the user was not invited.
- The user has been banned from the room. - The user has been banned from the room.
examples: examples:
application/json: |- application/json: {
{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:
@ -146,8 +145,7 @@ paths:
name: third_party_signed name: third_party_signed
schema: schema:
type: object type: object
example: |- example: {
{
"third_party_signed": { "third_party_signed": {
"signed": { "signed": {
"sender": "@cat:the.hat", "sender": "@cat:the.hat",
@ -193,8 +191,8 @@ paths:
The joined room ID must be returned in the ``room_id`` field. The joined room ID must be returned in the ``room_id`` field.
examples: examples:
application/json: |- application/json: {
{"room_id": "!d41d8cd:matrix.org"} "room_id": "!d41d8cd:matrix.org"}
schema: schema:
type: object type: object
403: 403:
@ -204,8 +202,8 @@ paths:
- The room is invite-only and the user was not invited. - The room is invite-only and the user was not invited.
- The user has been banned from the room. - The user has been banned from the room.
examples: examples:
application/json: |- application/json: {
{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:

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

@ -48,8 +48,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"reason": "Telling unfunny jokes", "reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org" "user_id": "@cheeky_monkey:matrix.org"
} }
@ -65,8 +64,8 @@ paths:
200: 200:
description: The user has been kicked from the room. description: The user has been kicked from the room.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
403: 403:
@ -77,8 +76,7 @@ paths:
- The kickee is not currently in the room. - The kickee is not currently in the room.
- The kicker's power level is insufficient to kick users from the room. - The kicker's power level is insufficient to kick users from the room.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room." "error": "You do not have a high enough power level to kick from this room."
} }

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

@ -56,8 +56,8 @@ paths:
description: |- description: |-
The room has been left. The room has been left.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
429: 429:
@ -93,8 +93,8 @@ paths:
description: |- description: |-
The room has been forgotten. The room has been forgotten.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
429: 429:

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

@ -132,8 +132,7 @@ paths:
An estimate on the total number of public rooms, if the An estimate on the total number of public rooms, if the
server has an estimate. server has an estimate.
examples: examples:
application/json: |- application/json: {
{
"chunk": [ "chunk": [
{ {
"aliases": ["#murrays:cheese.bar"], "aliases": ["#murrays:cheese.bar"],
@ -198,8 +197,8 @@ paths:
description: |- description: |-
A string to search for in the room metadata, e.g. name, A string to search for in the room metadata, e.g. name,
topic, canonical alias etc. (Optional). topic, canonical alias etc. (Optional).
example: |- example: {
{"limit": 10, "filter": {"generic_search_term": "foo"}} "limit": 10, "filter": {"generic_search_term": "foo"}}
responses: responses:
200: 200:
description: A list of the rooms on the server. description: A list of the rooms on the server.
@ -279,8 +278,7 @@ paths:
An estimate on the total number of public rooms, if the An estimate on the total number of public rooms, if the
server has an estimate. server has an estimate.
examples: examples:
application/json: |- application/json: {
{
"chunk": [ "chunk": [
{ {
"aliases": ["#murrays:cheese.bar"], "aliases": ["#murrays:cheese.bar"],

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

@ -46,8 +46,7 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"type": "m.login.password", "type": "m.login.password",
"user": "cheeky_monkey", "user": "cheeky_monkey",
"password": "ilovebananas", "password": "ilovebananas",
@ -93,8 +92,7 @@ paths:
200: 200:
description: The user has been authenticated. description: The user has been authenticated.
examples: examples:
application/json: |- application/json: {
{
"user_id": "@cheeky_monkey:matrix.org", "user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123", "access_token": "abc123",
"home_server": "matrix.org", "home_server": "matrix.org",
@ -123,8 +121,7 @@ paths:
description: |- description: |-
Part of the request was invalid. For example, the login type may not be recognised. Part of the request was invalid. For example, the login type may not be recognised.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_UNKNOWN", "errcode": "M_UNKNOWN",
"error": "Bad login type." "error": "Bad login type."
} }
@ -132,8 +129,8 @@ paths:
description: |- description: |-
The login attempt failed. For example, the password may have been incorrect. The login attempt failed. For example, the password may have been incorrect.
examples: examples:
application/json: |- application/json: {
{"errcode": "M_FORBIDDEN"} "errcode": "M_FORBIDDEN"}
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:

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

@ -107,8 +107,7 @@ paths:
type: object type: object
title: RoomEvent title: RoomEvent
examples: examples:
application/json: |- application/json: {
{
"start": "t47429-4392820_219380_26003_2265", "start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265", "end": "t47409-4357353_219380_26003_2265",
"chunk": [ "chunk": [

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

@ -62,8 +62,7 @@ paths:
200: 200:
description: A batch of events is being returned description: A batch of events is being returned
examples: examples:
application/json: |- application/json: {
{
"next_token": "abcdef", "next_token": "abcdef",
"notifications": [ "notifications": [
{ {

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

@ -59,8 +59,7 @@ paths:
200: 200:
description: "The events received, which may be none." description: "The events received, which may be none."
examples: examples:
application/json: |- application/json: {
{
"start": "s3456_9_0", "start": "s3456_9_0",
"end": "s3457_9_0", "end": "s3457_9_0",
"chunk": [ "chunk": [
@ -138,8 +137,7 @@ paths:
200: 200:
description: The user's current state. description: The user's current state.
examples: examples:
application/json: |- application/json: {
{
"end": "s3456_9_0", "end": "s3456_9_0",
"presence": [ "presence": [
{ {
@ -421,8 +419,7 @@ paths:
200: 200:
description: The full event. description: The full event.
examples: examples:
application/json: |- application/json: {
{
"content": { "content": {
"body": "Hello world!", "body": "Hello world!",
"msgtype": "m.text" "msgtype": "m.text"

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

@ -69,8 +69,7 @@ paths:
200: 200:
description: "The events received, which may be none." description: "The events received, which may be none."
examples: examples:
application/json: |- application/json: {
{
"start": "s3456_9_0", "start": "s3456_9_0",
"end": "s3457_9_0", "end": "s3457_9_0",
"chunk": [ "chunk": [

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

@ -50,8 +50,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"presence": "online", "presence": "online",
"status_msg": "I am here." "status_msg": "I am here."
} }
@ -68,8 +67,8 @@ paths:
200: 200:
description: The new presence state was set. description: The new presence state was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:
@ -93,8 +92,7 @@ paths:
200: 200:
description: The presence state for this user. description: The presence state for this user.
examples: examples:
application/json: |- application/json: {
{
"presence": "unavailable", "presence": "unavailable",
"last_active_ago": 420845 "last_active_ago": 420845
} }
@ -143,8 +141,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"invite": [ "invite": [
"@bob:matrix.org" "@bob:matrix.org"
], ],
@ -169,8 +166,8 @@ paths:
200: 200:
description: The list was updated. description: The list was updated.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:
@ -194,8 +191,7 @@ paths:
200: 200:
description: A list of presence events for this list. description: A list of presence events for this list.
examples: examples:
application/json: |- application/json: [
[
{ {
"content": { "content": {
"last_active_ago": 395, "last_active_ago": 395,

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

@ -48,8 +48,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"displayname": "Alice Margatroid" "displayname": "Alice Margatroid"
} }
properties: properties:
@ -60,8 +59,8 @@ paths:
200: 200:
description: The display name was set. description: The display name was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:
@ -87,8 +86,7 @@ paths:
200: 200:
description: The display name for this user. description: The display name for this user.
examples: examples:
application/json: |- application/json: {
{
"displayname": "Alice Margatroid" "displayname": "Alice Margatroid"
} }
schema: schema:
@ -122,8 +120,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34" "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
} }
properties: properties:
@ -134,8 +131,8 @@ paths:
200: 200:
description: The avatar URL was set. description: The avatar URL was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:
@ -161,8 +158,7 @@ paths:
200: 200:
description: The avatar URL for this user. description: The avatar URL for this user.
examples: examples:
application/json: |- application/json: {
{
"avatar_url": "mxc://matrix.org/SDGdghriugerRg" "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
} }
schema: schema:
@ -194,8 +190,7 @@ paths:
200: 200:
description: The avatar URL for this user. description: The avatar URL for this user.
examples: examples:
application/json: |- application/json: {
{
"avatar_url": "mxc://matrix.org/SDGdghriugerRg", "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid" "displayname": "Alice Margatroid"
} }

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

@ -38,8 +38,7 @@ paths:
200: 200:
description: The pushers for this user description: The pushers for this user
examples: examples:
application/json: |- application/json: {
{
"pushers": [ "pushers": [
{ {
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
@ -133,8 +132,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"lang": "en", "lang": "en",
"kind": "http", "kind": "http",
"app_display_name": "Mat Rix", "app_display_name": "Mat Rix",
@ -216,15 +214,14 @@ paths:
200: 200:
description: The pusher was set. description: The pusher was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
400: 400:
description: One or more of the pusher values were invalid. description: One or more of the pusher values were invalid.
examples: examples:
application/json: |- application/json: {
{
"error": "Missing parameters: lang, data", "error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM" "errcode": "M_MISSING_PARAM"
} }

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

@ -52,8 +52,7 @@ paths:
"$ref": "definitions/push_ruleset.yaml" "$ref": "definitions/push_ruleset.yaml"
] ]
examples: examples:
application/json: |- application/json: {
{
"global": { "global": {
"content": [ "content": [
{ {
@ -279,8 +278,7 @@ paths:
The specific push rule. This will also include keys specific to the The specific push rule. This will also include keys specific to the
rule itself such as the rule's ``actions`` and ``conditions`` if set. rule itself such as the rule's ``actions`` and ``conditions`` if set.
examples: examples:
application/json: |- application/json: {
{
"actions": [ "actions": [
"dont_notify" "dont_notify"
], ],
@ -330,8 +328,8 @@ paths:
200: 200:
description: The push rule was deleted. description: The push rule was deleted.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
tags: tags:
@ -393,8 +391,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"pattern": "cake*lie", "pattern": "cake*lie",
"actions": ["notify"] "actions": ["notify"]
} }
@ -425,15 +422,14 @@ paths:
200: 200:
description: The pusher was set. description: The pusher was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
400: 400:
description: There was a problem configuring this push rule. description: There was a problem configuring this push rule.
examples: examples:
application/json: |- application/json: {
{
"error": "before/after rule not found: someRuleId", "error": "before/after rule not found: someRuleId",
"errcode": "M_UNKNOWN" "errcode": "M_UNKNOWN"
} }
@ -480,8 +476,7 @@ paths:
200: 200:
description: Whether the push rule is enabled. description: Whether the push rule is enabled.
examples: examples:
application/json: |- application/json: {
{
"enabled": true "enabled": true
} }
schema: schema:
@ -532,16 +527,15 @@ paths:
type: boolean type: boolean
description: Whether the push rule is enabled or not. description: Whether the push rule is enabled or not.
required: ["enabled"] required: ["enabled"]
example: |- example: {
{
"enabled": true "enabled": true
} }
responses: responses:
200: 200:
description: The push rule was enabled or disabled. description: The push rule was enabled or disabled.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
tags: tags:
@ -581,8 +575,7 @@ paths:
200: 200:
description: The actions for this push rule. description: The actions for this push rule.
examples: examples:
application/json: |- application/json: {
{
"actions": ["notify"] "actions": ["notify"]
} }
schema: schema:
@ -640,16 +633,15 @@ paths:
enum: ["notify", "dont_notify", "coalesce", "set_tweak"] enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/ # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
required: ["actions"] required: ["actions"]
example: |- example: {
{
"actions": ["notify"] "actions": ["notify"]
} }
responses: responses:
200: 200:
description: The actions for the push rule were set. description: The actions for the push rule were set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
tags: tags:

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

@ -62,14 +62,14 @@ paths:
server will automatically set the ``ts`` field. server will automatically set the ``ts`` field.
schema: schema:
type: object type: object
example: |- example: {
{} }
responses: responses:
200: 200:
description: The receipt was sent. description: The receipt was sent.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:

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

@ -66,8 +66,7 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"reason": "Indecent material" "reason": "Indecent material"
} }
properties: properties:
@ -78,8 +77,7 @@ paths:
200: 200:
description: "An ID for the redaction event." description: "An ID for the redaction event."
examples: examples:
application/json: |- application/json: {
{
"event_id": "YUwQidLecu" "event_id": "YUwQidLecu"
} }
schema: schema:

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

@ -110,8 +110,7 @@ paths:
200: 200:
description: The account has been registered. description: The account has been registered.
examples: examples:
application/json: |- application/json: {
{
"user_id": "@cheeky_monkey:matrix.org", "user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123", "access_token": "abc123",
"home_server": "matrix.org", "home_server": "matrix.org",
@ -154,8 +153,7 @@ paths:
them after authentication is completed if, for example, the requested user ID them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication. was registered whilst the client was performing authentication.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_USER_IN_USE", "errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken." "error": "Desired user ID is already taken."
} }
@ -210,7 +208,7 @@ paths:
Note that this may be an email containing the validation token or it may be informing Note that this may be an email containing the validation token or it may be informing
the user of an error. the user of an error.
examples: examples:
application/json: "{}" application/json: {}
schema: schema:
type: object type: object
400: 400:
@ -225,8 +223,7 @@ paths:
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
that is not trusted by this Home Server. that is not trusted by this Home Server.
examples: examples:
application/json: |- application/json: {
{
"errcode": "M_THREEPID_IN_USE", "errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use" "error": "The specified address is already in use"
} }
@ -266,7 +263,7 @@ paths:
200: 200:
description: The password has been changed. description: The password has been changed.
examples: examples:
application/json: "{}" application/json: {}
schema: schema:
type: object type: object
401: 401:
@ -331,7 +328,7 @@ paths:
200: 200:
description: The account has been deactivated. description: The account has been deactivated.
examples: examples:
application/json: "{}" application/json: {}
schema: schema:
type: object type: object
401: 401:

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

@ -37,8 +37,7 @@ paths:
200: 200:
description: The current state of the room description: The current state of the room
examples: examples:
application/json: |- application/json: {
{
"membership": "join", "membership": "join",
"messages": { "messages": {
"chunk": [ "chunk": [

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

@ -66,8 +66,7 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"msgtype": "m.text", "msgtype": "m.text",
"body": "hello" "body": "hello"
} }
@ -75,8 +74,7 @@ paths:
200: 200:
description: "An ID for the sent event." description: "An ID for the sent event."
examples: examples:
application/json: |- application/json: {
{
"event_id": "YUwRidLecu" "event_id": "YUwRidLecu"
} }
schema: schema:

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

@ -67,8 +67,7 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"membership": "join", "membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid" "displayname": "Alice Margatroid"
@ -77,8 +76,7 @@ paths:
200: 200:
description: "An ID for the sent event." description: "An ID for the sent event."
examples: examples:
application/json: |- application/json: {
{
"event_id": "YUwRidLecu" "event_id": "YUwRidLecu"
} }
schema: schema:
@ -125,16 +123,14 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"name": "New name for the room" "name": "New name for the room"
} }
responses: responses:
200: 200:
description: "An ID for the sent event." description: "An ID for the sent event."
examples: examples:
application/json: |- application/json: {
{
"event_id": "YUwRidLecu" "event_id": "YUwRidLecu"
} }
schema: schema:

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

@ -60,8 +60,8 @@ paths:
200: 200:
description: The content of the state event. description: The content of the state event.
examples: examples:
application/json: |- application/json: {
{"name": "Example room name"} "name": "Example room name"}
schema: schema:
type: object type: object
404: 404:
@ -101,8 +101,8 @@ paths:
200: 200:
description: The content of the state event. description: The content of the state event.
examples: examples:
application/json: |- application/json: {
{"name": "Example room name"} "name": "Example room name"}
schema: schema:
type: object type: object
404: 404:
@ -131,8 +131,7 @@ paths:
200: 200:
description: The current state of the room description: The current state of the room
examples: examples:
application/json: |- application/json: [
[
{ {
"age": 7148266897, "age": 7148266897,
"content": { "content": {
@ -249,8 +248,7 @@ paths:
this will be the current members of the room. If you have left the this will be the current members of the room. If you have left the
room then this will be the members of the room when you left. room then this will be the members of the room when you left.
examples: examples:
application/json: |- application/json: {
{
"chunk": [ "chunk": [
{ {
"age": 6547561012, "age": 6547561012,

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

@ -46,8 +46,7 @@ paths:
name: body name: body
schema: schema:
type: object type: object
example: |- example: {
{
"search_categories": { "search_categories": {
"room_events": { "room_events": {
"keys": [ "keys": [
@ -297,8 +296,7 @@ paths:
the next call. If this field is absent, there are no the next call. If this field is absent, there are no
more results. more results.
examples: examples:
application/json: |- application/json: {
{
"search_categories": { "search_categories": {
"room_events": { "room_events": {
"groups": { "groups": {

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

@ -253,8 +253,7 @@ paths:
Information on end-to-end device updates, as specified in Information on end-to-end device updates, as specified in
|device_lists_sync|_. |device_lists_sync|_.
examples: examples:
application/json: |- application/json: {
{
"next_batch": "s72595_4483_1934", "next_batch": "s72595_4483_1934",
"presence": { "presence": {
"events": [ "events": [

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

@ -61,8 +61,7 @@ paths:
title: Tags title: Tags
type: object type: object
examples: examples:
application/json: |- application/json: {
{
"tags": { "tags": {
"work": {"order": "1"}, "work": {"order": "1"},
"pinned": {} "pinned": {}
@ -107,8 +106,8 @@ paths:
Extra data for the tag, e.g. ordering. Extra data for the tag, e.g. ordering.
schema: schema:
type: object type: object
example: |- example: {
{"order": "1"} "order": "1"}
responses: responses:
200: 200:
description: description:
@ -116,8 +115,8 @@ paths:
schema: schema:
type: object type: object
examples: examples:
application/json: |- application/json: {
{} }
tags: tags:
- User data - User data
delete: delete:
@ -156,7 +155,7 @@ paths:
schema: schema:
type: object type: object
examples: examples:
application/json: |- application/json: {
{} }
tags: tags:
- User data - User data

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

@ -89,8 +89,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"id_server": "matrix.org", "id_server": "matrix.org",
"medium": "email", "medium": "email",
"address": "cheeky@monkey.com" "address": "cheeky@monkey.com"
@ -111,8 +110,8 @@ paths:
200: 200:
description: The user has been invited to join the room. description: The user has been invited to join the room.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object type: object
403: 403:
@ -124,8 +123,8 @@ paths:
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
examples: examples:
application/json: |- application/json: {
{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:

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

@ -83,7 +83,7 @@ paths:
description: description:
The message was successfully sent. The message was successfully sent.
examples: examples:
application/json: |- application/json: {
{} }
tags: tags:
- Send-to-Device messaging - Send-to-Device messaging

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

@ -56,8 +56,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"typing": true, "typing": true,
"timeout": 30000 "timeout": 30000
} }
@ -75,8 +74,8 @@ paths:
200: 200:
description: The new typing state was set. description: The new typing state was set.
examples: examples:
application/json: |- application/json: {
{} }
schema: schema:
type: object # empty json object type: object # empty json object
429: 429:

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

@ -37,8 +37,7 @@ paths:
200: 200:
description: The versions supported by the server. description: The versions supported by the server.
examples: examples:
application/json: |- application/json: {
{
"versions": ["r0.0.1"] "versions": ["r0.0.1"]
} }
schema: schema:

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

@ -39,8 +39,7 @@ paths:
200: 200:
description: The TURN server credentials. description: The TURN server credentials.
examples: examples:
application/json: |- application/json: {
{
"username":"1443779631:@user:example.com", "username":"1443779631:@user:example.com",
"password":"JlKfBy1QwLrO20385QyAtEyIv0=", "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
"uris":[ "uris":[

3
api/identity/lookup.yaml
View file

@ -45,8 +45,7 @@ paths:
description: description:
The association for that 3pid, or the empty object if no association is known. The association for that 3pid, or the empty object if no association is known.
examples: examples:
application/json: |- application/json: {
{
"address": "louise@bobs.burgers", "address": "louise@bobs.burgers",
"medium": "email", "medium": "email",
"mxid": "@ears:matrix.org", "mxid": "@ears:matrix.org",

9
api/identity/pubkey.yaml
View file

@ -43,8 +43,7 @@ paths:
description: description:
The public key exists. The public key exists.
examples: examples:
application/json: |- application/json: {
{
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
} }
schema: schema:
@ -70,8 +69,7 @@ paths:
description: description:
The validity of the public key. The validity of the public key.
examples: examples:
application/json: |- application/json: {
{
"valid": true "valid": true
} }
schema: schema:
@ -98,8 +96,7 @@ paths:
description: description:
The validity of the public key. The validity of the public key.
examples: examples:
application/json: |- application/json: {
{
"valid": true "valid": true
} }
schema: schema:

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

@ -54,8 +54,7 @@ paths:
required: true required: true
schema: schema:
type: object type: object
example: |- example: {
{
"notification": { "notification": {
"id": "$3957tyerfgewrf384", "id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com", "room_id": "!slw48wfj34rtnrf:example.com",
@ -207,8 +206,7 @@ paths:
200: 200:
description: A list of rejected push keys. description: A list of rejected push keys.
examples: examples:
application/json: |- application/json: {
{
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
} }
schema: schema: