Swaggerify the /enabled endpoint
This commit is contained in:
Kegan Dougal
parent
56ce432399
commit
a9618a981b
5 changed files with 112 additions and 39 deletions
|
|
@ -52,7 +52,7 @@ def check_parameter(filepath, request, parameter):
|
|||
jsonschema.validate(example, schema)
|
||||
except Exception as e:
|
||||
raise ValueError("Error validating JSON schema for %r %r" % (
|
||||
request, code
|
||||
request
|
||||
), e)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -436,4 +436,51 @@ paths:
|
|||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/error.yaml"
|
||||
|
||||
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
|
||||
put:
|
||||
summary: "Enable or disable a push rule."
|
||||
description: |-
|
||||
This endpoint allows clients to enable or disable the specified push rule.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: scope
|
||||
required: true
|
||||
x-example: "global"
|
||||
description: |-
|
||||
Either ``global`` or ``device/<profile_tag>`` to specify global
|
||||
rules or device rules for the given ``profile_tag``.
|
||||
- in: path
|
||||
type: string
|
||||
name: kind
|
||||
required: true
|
||||
x-example: room
|
||||
enum: ["override", "underride", "sender", "room", "content"]
|
||||
description: |
|
||||
The kind of rule
|
||||
- in: path
|
||||
type: string
|
||||
name: ruleId
|
||||
required: true
|
||||
x-example: "#spam:example.com"
|
||||
description: |
|
||||
The identifier for the rule.
|
||||
- in: body
|
||||
name: <body>
|
||||
description: |
|
||||
Whether the push rule is enabled or not.
|
||||
required: true
|
||||
schema:
|
||||
type: boolean
|
||||
example: |-
|
||||
true
|
||||
responses:
|
||||
200:
|
||||
description: The push rule was enabled or disabled.
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
schema:
|
||||
type: object # empty json object
|
||||
|
|
|
|||
|
|
@ -110,7 +110,7 @@ Underride
|
|||
|
||||
In addition, each kind of rule may be either global or device-specific. Device
|
||||
specific rules only affect delivery of notifications via pushers with a matching
|
||||
profile_tag. All device-specific rules are higher priority than all global
|
||||
``profile_tag``. All device-specific rules are higher priority than all global
|
||||
rules. Thusly, the full list of rule kinds, in descending priority order, is as
|
||||
follows:
|
||||
|
||||
|
|
@ -145,7 +145,7 @@ If no rules match an event, the Home Server should not notify for the message
|
|||
themselves are never alerted for.
|
||||
|
||||
Predefined Rules
|
||||
~~~~~~~~~~~~~~~~
|
||||
++++++++++++++++
|
||||
Matrix specifies the following rule IDs for server default rules. Home Servers
|
||||
may define rules as follows with the given IDs. If Home Servers provide rules
|
||||
with these IDs, their semantics should match those given below:
|
||||
|
|
@ -247,8 +247,8 @@ with these IDs, their semantics should match those given below:
|
|||
],
|
||||
}
|
||||
|
||||
Push Rules: Actions:
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Actions
|
||||
+++++++
|
||||
All rules have an associated list of 'actions'. An action affects if and how a
|
||||
notification is delivered for a matching event. This standard defines the
|
||||
following actions, although if Home servers wish to support more, they are free
|
||||
|
|
@ -273,8 +273,8 @@ Actions that have no parameters are represented as a string. Otherwise, they are
|
|||
represented as a dictionary with a key equal to their name and other keys as
|
||||
their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }``
|
||||
|
||||
Push Rules: Actions: Tweaks
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Tweaks
|
||||
^^^^^^
|
||||
The ``set_tweak`` key action is used to add an entry to the 'tweaks' dictionary
|
||||
that is sent in the notification poke. The following tweaks are defined:
|
||||
|
||||
|
|
@ -295,8 +295,8 @@ notification light on a mobile device.
|
|||
If a kind of tweak that a client understands is not specified in an action, the
|
||||
client may choose a sensible behaviour for the tweak.
|
||||
|
||||
Push Rules: Conditions
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Conditions
|
||||
++++++++++
|
||||
Override, Underride and Default rules have a list of 'conditions'. All
|
||||
conditions must hold true for an event in order for a rule to be applied to an
|
||||
event. A rule with no conditions always matches. Matrix specifies the following
|
||||
|
|
@ -332,44 +332,65 @@ but instead have predefined conditions, the behaviour of which can be configured
|
|||
using parameters named as described above. In the cases of room and sender
|
||||
rules, the rule_id of the rule determines its behaviour.
|
||||
|
||||
{{pushrules_http_api}}
|
||||
|
||||
Push Rules: API
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The content of the PUT request is a JSON object with a list of actions under the
|
||||
'actions' key and either conditions (under the 'conditions' key) or the
|
||||
appropriate parameters for the rule (under the appropriate key name).
|
||||
Clients can retrieve, add, modify and remove push rules globally or per-device
|
||||
using the APIs below.
|
||||
|
||||
Examples:
|
||||
{{pushrules_http_api}}
|
||||
|
||||
To create a rule that suppresses notifications for the room with ID '!dj234r78wl45Gh4D:matrix.org'::
|
||||
Examples
|
||||
++++++++
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456"
|
||||
To create a rule that suppresses notifications for the room with ID
|
||||
``!dj234r78wl45Gh4D:matrix.org``::
|
||||
|
||||
To suppress notifications for the user '@spambot:matrix.org'::
|
||||
curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
|
||||
'{
|
||||
"actions" : ["dont_notify"]
|
||||
}'
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456"
|
||||
To suppress notifications for the user ``@spambot:matrix.org``::
|
||||
|
||||
To always notify for messages that contain the work 'cake' and set a specific sound (with a rule_id of 'SSByZWFsbHkgbGlrZSBjYWtl')::
|
||||
curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
|
||||
'{
|
||||
"actions" : ["dont_notify"]
|
||||
}'
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456"
|
||||
To always notify for messages that contain the work 'cake' and set a specific
|
||||
sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``)::
|
||||
|
||||
To add a rule suppressing notifications for messages starting with 'cake' but ending with 'lie', superseeding the previous rule::
|
||||
curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
|
||||
'{
|
||||
"pattern": "cake",
|
||||
"actions" : ["notify", {"set_sound":"cakealarm.wav"}]
|
||||
}'
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake*lie", "actions" : ["notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl"
|
||||
To add a rule suppressing notifications for messages starting with 'cake' but
|
||||
ending with 'lie', superseding the previous rule::
|
||||
|
||||
To add a custom sound for notifications messages containing the word 'beer' in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules)::
|
||||
curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
|
||||
'{
|
||||
"pattern": "cake*lie",
|
||||
"actions" : ["notify"]
|
||||
}'
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{ "conditions": [{"kind": "event_match", "key": "content.body", "pattern": "beer" }, {"kind": "room_member_count", "is": "<=10"}], "actions" : ["notify", {"set_sound":"beeroclock.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456
|
||||
To add a custom sound for notifications messages containing the word 'beer' in
|
||||
any rooms with 10 members or fewer (with greater importance than the room,
|
||||
sender and content rules)::
|
||||
|
||||
|
||||
Enabling and Disabling Rules
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Rules can be enabled or disabled with a PUT operation to the 'enabled' component
|
||||
beneath the rule's URI with a content of 'true' or 'false'::
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" -d 'false' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org/enabled?access_token=123456"
|
||||
curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
|
||||
'{
|
||||
"conditions": [
|
||||
{"kind": "event_match", "key": "content.body", "pattern": "beer" },
|
||||
{"kind": "room_member_count", "is": "<=10"}
|
||||
],
|
||||
"actions" : [
|
||||
"notify",
|
||||
{"set_sound":"beeroclock.wav"}
|
||||
]
|
||||
}'
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
|
|
@ -504,8 +525,11 @@ rejected
|
|||
necessarily be the notification in the request that failed: it could be that
|
||||
a previous notification to the same pushkey failed.
|
||||
|
||||
Push: Recommendations for APNS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Push Gateway behaviour
|
||||
----------------------
|
||||
|
||||
Recommendations for APNS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
For sending APNS notifications, the exact format is flexible and up to the
|
||||
client app and its push gateway to agree on (since APNS requires that the sender
|
||||
have a private key owned by the app developer, each app must have its own push
|
||||
|
|
@ -518,9 +542,6 @@ gateway). However, Matrix strongly recommends:
|
|||
gateway before returning and instead to store failures and return
|
||||
'rejected' responses next time that pushkey is used.
|
||||
|
||||
Push Gateway behaviour
|
||||
----------------------
|
||||
|
||||
Security considerations
|
||||
-----------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
|
|||
- modules/history_visibility.rst
|
||||
- modules/push.rst
|
||||
|
||||
title_styles: ["=", "-", "~", "+", "^"]
|
||||
title_styles: ["=", "-", "~", "+", "^", "`"]
|
||||
|
||||
# The templating system doesn't know the right title style to use when generating
|
||||
# RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title
|
||||
|
|
|
|||
|
|
@ -184,6 +184,11 @@ class MatrixUnits(Units):
|
|||
val_type = refType # TODO: Resolve to human-readable.
|
||||
if not val_type and schemaFmt:
|
||||
val_type = schemaFmt
|
||||
# handle top-level strings/bools
|
||||
if not val_type and Units.prop(param, "schema/type") == "string":
|
||||
val_type = "string"
|
||||
if not val_type and Units.prop(param, "schema/type") == "boolean":
|
||||
val_type = "boolean"
|
||||
if val_type:
|
||||
endpoint["req_params"].append({
|
||||
"key": param["name"],
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue