diff --git a/api/client-server/v1/push.yaml b/api/client-server/v1/push.yaml new file mode 100644 index 00000000..fd179fe6 --- /dev/null +++ b/api/client-server/v1/push.yaml @@ -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" + diff --git a/specification/modules/push.rst b/specification/modules/push.rst index addd92b6..bd08dc9e 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -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 ~~~~~~~~~~ diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl index 472c9d7a..f2c3d0b6 100644 --- a/templating/matrix_templates/templates/http-api.tmpl +++ b/templating/matrix_templates/templates/http-api.tmpl @@ -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 -%} diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index eebfba84..1b4b8c7d 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -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"]: