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

Require explicit un-banning

Browse source
This commit is contained in:
Daniel Wagner-Hall 2016-01-15 14:08:40 +00:00 • committed by review.rocks
parent c69481d67a
commit 2e46b587b8
3 changed files with 169 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -24,7 +24,7 @@ paths:
description: |-
Ban a user in the room. If the user is currently in the room, also kick them.
When a user is banned from a room, they may not join it until they are unbanned.
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.
security:
@ -76,3 +76,55 @@ paths:
}
tags:
- Room membership
"/rooms/{roomId}/unban":
post:
summary: Unban a user from the room.
description: |-
Unban a user from the room. This allows them to be invited to the room,
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.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be unbanned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: |-
{
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: |-
{}
schema:
type: object
403:
description: |-
You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
tags:
- Room membership

77
api/client-server/kicking.yaml Normal file
View file

@ -0,0 +1,77 @@
swagger: '2.0'
info:
title: "Matrix Client-Server Room Kicking API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
accessToken:
type: apiKey
description: The user_id or application service access_token
name: access_token
in: query
paths:
"/rooms/{roomId}/kick":
post:
summary: Kick a user from the room.
description: |-
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be kicked.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: |-
{
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being kicked.
reason:
type: string
description: The reason the user has been kicked.
required: ["user_id"]
responses:
200:
description: The user has been kicked from the room.
examples:
application/json: |-
{}
schema:
type: object
403:
description: |-
You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
- The kicker 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.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
tags:
- Room membership

41
specification/client_server_api.rst
View file

@ -914,10 +914,42 @@ following values:
``invite``
This room can only be joined if you were invited.
The allowable state transitions of membership are::
/ban
+------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | /leave | | | |
| | v v | |
/invite +--------+ +-------+ | |
------------>| invite |<----------| leave |----+ | |
+--------+ /invite +-------+ | | |
| | ^ | | |
| | | | | |
/join | +---------------+ | | | |
| | /join if | | | |
| | join_rules | | /ban | /unban |
| | public /leave | | | |
v v or | | | |
+------+ /kick | | | |
------------>| join |-------------------+ | | |
/join +------+ v | |
if | +-----+ | |
join_rules +-------------------------->| ban |-----+ |
public /ban +-----+ |
^ ^ |
| | |
----------------------------------------------+ +----------------------+
/ban
{{inviting_http_api}}
{{joining_http_api}}
{{kicking_http_api}}
{{banning_http_api}}
Leaving rooms
@ -947,8 +979,7 @@ to |/rooms/<room_id>/ban|_ with::
"reason": "string: <reason for the ban>"
}
Banning a user adjusts the banned member's membership state to ``ban`` and
adjusts the power level of this event to a level higher than the banned person.
Banning a user adjusts the banned member's membership state to ``ban``.
Like with other membership changes, a user can directly adjust the target
member's state, by making a request to
``/rooms/<room id>/state/m.room.member/<user id>``::
@ -957,6 +988,9 @@ member's state, by making a request to
"membership": "ban"
}
A user must be explicitly unbanned with a request to |/rooms/<room_id>/unban|_
before they can re-join the room or be re-invited.
Listing rooms
~~~~~~~~~~~~~
@ -1048,3 +1082,6 @@ have to wait in milliseconds before they can try again.
.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
.. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
.. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
.. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban