mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
820704a16a
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.
236 lines
9.1 KiB
YAML
236 lines
9.1 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Push API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/pushers":
|
|
get:
|
|
summary: Gets the current pushers for the authenticated user
|
|
description: |-
|
|
Gets all currently active pushers for the authenticated user
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The pushers for this user
|
|
examples:
|
|
application/json: {
|
|
"pushers": [
|
|
{
|
|
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
|
|
"kind": "http",
|
|
"app_id": "face.mcapp.appy.prod",
|
|
"app_display_name": "Appy McAppface",
|
|
"device_display_name": "Alice's Phone",
|
|
"profile_tag": "xyz",
|
|
"lang": "en-US",
|
|
"data": {
|
|
"url": "https://example.com/_matrix/push/v1/notify"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pushers:
|
|
type: array
|
|
title: Pushers
|
|
description: |-
|
|
An array containing the current pushers for the user
|
|
items:
|
|
type: object
|
|
title: Pusher
|
|
properties:
|
|
pushkey:
|
|
type: string
|
|
description: |-
|
|
This is a unique identifier for this pusher. See `/set` for
|
|
more detail.
|
|
Max length, 512 bytes.
|
|
kind:
|
|
type: string
|
|
description: |-
|
|
The kind of pusher. ``"http"`` is a pusher that
|
|
sends HTTP pokes.
|
|
app_id:
|
|
type: string
|
|
description: |-
|
|
This is a reverse-DNS style identifier for the application.
|
|
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.
|
|
profile_tag:
|
|
type: string
|
|
description: |-
|
|
This string determines which set of device specific rules this
|
|
pusher executes.
|
|
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.
|
|
title: PusherData
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: |-
|
|
Required if ``kind`` is ``http``. The URL to use to send
|
|
notifications to.
|
|
tags:
|
|
- Push notifications
|
|
"/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",
|
|
"profile_tag": "xxyyzz",
|
|
"app_id": "com.example.app.ios",
|
|
"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
|
|
description: |-
|
|
The kind of pusher to configure. ``"http"`` makes a pusher that
|
|
sends HTTP pokes. ``null`` deletes the pusher.
|
|
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.
|
|
profile_tag:
|
|
type: string
|
|
description: |-
|
|
This string determines which set of device specific rules this
|
|
pusher executes.
|
|
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.
|
|
title: PusherData
|
|
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 homeserver must remove any
|
|
other pushers with the same App ID and pushkey for different
|
|
users. The default is ``false``.
|
|
required: ['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"
|
|
tags:
|
|
- Push notifications
|