Add push YAML for pushers endpoint.

Also display "required" text on required JSON body request params. Also
increase the size of the request param column to support longer param names
present in the pushers API.
module-push
Kegan Dougal 9 years ago
parent d3ed517ebf
commit c5edc60c4c

@ -0,0 +1,144 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Push API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
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:
"/pushers/set":
post:
summary: Modify a pusher for this user on the homeserver.
description: |-
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.
security:
- accessToken: []
parameters:
- in: body
name: pusher
description: The pusher information
required: true
schema:
type: object
example: |-
{
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"app_id": "com.example.app.ios",
"profile_tag": "4bea66906d0111e59d70feff819cdc9f",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ"
"data": {
"url": "https://push-gateway.location.here"
}
"append": false
}
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. The value you
should use for this is the routing or destination address
information for the notification, for example, the APNS token
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
kind:
type: string
enum: ["http", null]
description: |-
The kind of pusher to configure. 'http' makes a pusher that
sends HTTP pokes. null deletes the pusher.
profile_tag:
type: string
description: |-
This is a string that determines what set of device rules will
be matched when evaluating push rules for this pusher. It is
an arbitrary string. Multiple devices maybe use the same
``profile_tag``. It is advised that when an app's data is
copied or restored to a different device, this value remain
the same. Client apps should offer ways to change the
``profile_tag``, optionally copying rules from the old
profile tag. Max length, 32 bytes.
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
app_display_name:
type: string
description: |-
A string that will allow the user to identify what application
owns this pusher.
device_display_name:
type: string
description: |-
A string that will allow the user to identify what device owns
this pusher.
lang:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
data:
type: object
description: |-
A dictionary of information for the pusher implementation
itself. If ``kind`` is ``http``, this should contain ``url``
which is the URL to use to send notifications to.
properties:
url:
type: string
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to.
append:
type: boolean
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the Home Server must remove any
other pushers with the same App ID and pushkey for different
users. The default is ``false``.
required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
'device_display_name', 'pushkey', 'lang', 'data']
responses:
200:
description: The pusher was set.
examples:
application/json: |-
{}
schema:
type: object # empty json object
400:
description: One or more of the pusher values were invalid.
examples:
application/json: |-
{
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"

@ -79,52 +79,9 @@ Client behaviour
To receive any notification pokes at all, it is necessary to configure a
'pusher' on the Home Server that you wish to receive notifications from. There
is a single API endpoint for this::
POST $PREFIX/pushers/set
This takes a JSON object with the following keys:
pushkey
This is a unique identifier for this pusher. The value you should use for this
is the routing or destination address information for the notification, for
example, the APNS token for APNS or the Registration ID for GCM. If your
notification client has no such concept, use any unique identifier. Max length,
512 bytes.
kind
The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes.
null deletes the pusher.
profile_tag
This is a string that determines what set of device rules will be matched when
evaluating push rules for this pusher. It is an arbitrary string. Multiple
devices maybe use the same profile_tag. It is advised that when an app's
data is copied or restored to a different device, this value remain the same.
Client apps should offer ways to change the profile_tag, optionally copying
rules from the old profile tag. Max length, 32 bytes.
app_id
appId is a reverse-DNS style identifier for the application. It is recommended
that this end with the platform, such that different platform versions get
different app identifiers. Max length, 64 chars.
app_display_name
A string that will allow the user to identify what application owns this
pusher.
device_display_name
A string that will allow the user to identify what device owns this pusher.
lang
The preferred language for receiving notifications (eg, 'en' or 'en-US')
data
A dictionary of information for the pusher implementation itself. For HTTP
pushers, this must contain a 'url' key which is a string of the URL that
should be used to send notifications.
append
If this is set to boolean true, the Home Server should add another pusher
with the given pushkey and App ID in addition to any others with different
user IDs. Otherwise, the Home Server must remove any other pushers with the
same App ID and pushkey for different users. The default is false.
If the pusher was created successfully, a JSON dictionary is returned (which may
be empty).
is a single API endpoint for this, as described below.
{{push_http_api}}
Push Rules
~~~~~~~~~~

@ -13,17 +13,17 @@
Request format:
================== ================= ===========================================
====================== ================= ===========================================
Parameter Value Description
================== ================= ===========================================
====================== ================= ===========================================
{% for loc in endpoint.req_param_by_loc -%}
*{{loc}} parameters*
--------------------------------------------------------------------------------
------------------------------------------------------------------------------------
{% for param in endpoint.req_param_by_loc[loc] -%}
{{param.key}}{{param.type|indent(19-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}}
{{param.key}}{{param.type|indent(23-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(41)}}
{% endfor -%}
{% endfor -%}
================== ================= ===========================================
====================== ================= ===========================================
{% if endpoint.res_tables|length > 0 -%}
Response format:
@ -31,18 +31,18 @@ Response format:
{% for table in endpoint.res_tables -%}
{{"``"+table.title+"``" if table.title else "" }}
=================== ================= ==========================================
======================= ================= ==========================================
Param Type Description
=================== ================= ==========================================
======================= ================= ==========================================
{% for row in table.rows -%}
{# -#}
{# Row type needs to prepend spaces to line up with the type column (20 ch) -#}
{# Desc needs to prepend the required text (maybe) and prepend spaces too -#}
{# It also needs to then wrap inside the desc col (42 ch width) -#}
{# -#}
{{row.key}}{{row.type|indent(20-row.key|length)}}{{row.desc|wrap(42,row.req_str | indent(18 - (row.type|length))) |indent_block(38)}}
{{row.key}}{{row.type|indent(24-row.key|length)}}{{row.desc|wrap(40,row.req_str | indent(18 - (row.type|length))) |indent_block(42)}}
{% endfor -%}
=================== ================= ==========================================
======================= ================= ==========================================
{% endfor %}
{% endif -%}

@ -207,12 +207,18 @@ class MatrixUnits(Units):
)
# loop top-level json keys
json_body = Units.prop(param, "schema/properties")
required_params = []
if Units.prop(param, "schema/required"):
required_params = Units.prop(param, "schema/required")
for key in json_body:
pdesc = json_body[key]["description"]
if key in required_params:
pdesc = "**Required.** " + pdesc
endpoint["req_params"].append({
"key": key,
"loc": "JSON body",
"type": json_body[key]["type"],
"desc": json_body[key]["description"]
"desc": pdesc
})
# endfor[param]
for row in endpoint["req_params"]:

Loading…
Cancel
Save