---
openapi: 3.0.1
info:
title: mod_rest API
version: 0.3.2
description: |
API for sending and receiving stanzas, in a REST-ish fashion or by
responding to webhooks. Multiple formats supported, including native XML
and a simplified JSON mapping.
license:
name: MIT
paths:
/rest:
post:
summary: Send stanzas and receive responses. Webhooks work the same way.
tags:
- generic
security:
- basic: []
- token: []
requestBody:
$ref: '#/components/requestBodies/common'
responses:
'200':
$ref: '#/components/responses/success'
'202':
$ref: '#/components/responses/sent'
/rest/{kind}/{type}/{to}:
post:
summary: Even more RESTful mapping with certain components in the path.
tags:
- generic
security:
- basic: []
- token: []
parameters:
- $ref: '#/components/parameters/kind'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/to'
requestBody:
$ref: '#/components/requestBodies/common'
responses:
'200':
$ref: '#/components/responses/success'
/rest/echo:
post:
summary: Build as stanza and return it for inspection.
tags:
- debug
security:
- basic: []
- token: []
requestBody:
$ref: '#/components/requestBodies/common'
responses:
'200':
$ref: '#/components/responses/success'
/rest/ping/{to}:
get:
tags:
- query
summary: Ping a local or remote server or other entity
security:
- basic: []
- token: []
parameters:
- $ref: '#/components/parameters/to'
responses:
'200':
description: Test reachability of some address
content:
application/json:
schema:
$ref: '#/components/schemas/iq_pong'
application/xmpp+xml:
schema:
$ref: '#/components/schemas/iq_pong'
/rest/version/{to}:
get:
tags:
- query
summary: Ask what software version is used.
security:
- basic: []
- token: []
parameters:
- $ref: '#/components/parameters/to'
responses:
'200':
description: Version query response
content:
application/json:
schema:
$ref: '#/components/schemas/iq_result_version'
application/xmpp+xml:
schema:
$ref: '#/components/schemas/iq_result_version'
/rest/disco/{to}:
get:
tags:
- query
summary: Query a remote entity for supported features
security:
- basic: []
- token: []
parameters:
- $ref: '#/components/parameters/to'
responses:
'200':
$ref: '#/components/responses/success'
/rest/items/{to}:
get:
tags:
- query
summary: Query an entity for related services, chat rooms or other items
security:
- basic: []
- token: []
parameters:
- $ref: '#/components/parameters/to'
responses:
'200':
$ref: '#/components/responses/success'
components:
schemas:
stanza:
type: object
example:
body: Hello
type: chat
kind: message
to: alice@example.com
state: active
oneOf:
- $ref: '#/components/schemas/message'
- $ref: '#/components/schemas/presence'
- $ref: '#/components/schemas/iq'
message:
type: object
xml:
name: message
properties:
kind:
description: Which kind of stanza
type: string
enum:
- message
type:
type: string
enum:
- chat
- error
- groupchat
- headline
- normal
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
body:
$ref: '#/components/schemas/body'
subject:
$ref: '#/components/schemas/subject'
thread:
$ref: '#/components/schemas/thread'
state:
$ref: '#/components/schemas/state'
nick:
$ref: '#/components/schemas/nick'
delay:
$ref: '#/components/schemas/delay'
replace:
$ref: '#/components/schemas/replace'
html:
$ref: '#/components/schemas/html'
oob:
$ref: '#/components/schemas/oob'
error:
$ref: '#/components/schemas/error'
presence:
type: object
properties:
kind:
kind:
description: Which kind of stanza
type: string
enum:
- presence
type:
type: string
enum:
- available
- unavailable
- subscribe
- subscribed
- unsubscribe
- unsubscribed
- error
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
show:
$ref: '#/components/schemas/show'
status:
$ref: '#/components/schemas/status'
priority:
$ref: '#/components/schemas/priority'
caps:
$ref: '#/components/schemas/caps'
nick:
$ref: '#/components/schemas/nick'
delay:
$ref: '#/components/schemas/delay'
join:
$ref: '#/components/schemas/join'
error:
$ref: '#/components/schemas/error'
iq:
type: object
properties:
kind:
description: Which kind of stanza
type: string
enum:
- iq
type:
type: string
enum:
- get
- set
- result
- error
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
ping:
$ref: '#/components/schemas/ping'
version:
$ref: '#/components/schemas/version'
disco:
$ref: '#/components/schemas/disco'
items:
$ref: '#/components/schemas/items'
command:
$ref: '#/components/schemas/command'
stats:
$ref: '#/components/schemas/stats'
payload:
$ref: '#/components/schemas/payload'
error:
$ref: '#/components/schemas/error'
iq_pong:
description: Test reachability of some XMPP address
type: object
xml:
name: iq
properties:
type:
type: string
enum:
- result
xml:
attribute: true
iq_result_version:
description: Version query response
type: object
xml:
name: iq
properties:
type:
type: string
enum:
- result
xml:
attribute: true
version:
$ref: '#/components/schemas/version'
kind:
description: Which kind of stanza
type: string
enum:
- message
- presence
- iq
type:
description: Stanza type
type: string
enum:
- chat
- normal
- headline
- groupchat
- get
- set
- result
- available
- unavailable
- subscribe
- subscribed
- unsubscribe
- unsubscribed
to:
description: recipient
example: alice@example.com
type: string
from:
description: the sender
example: bob@localhost.example
type: string
id:
description: Reasonably unique id. mod_rest generates one if left out.
type: string
lang:
description: Language code
example: en
type: string
body:
description: Human-readable chat message
example: Hello, World!
type: string
subject:
description: Subject of message or group chat
example: Talking about stuff
type: string
thread:
description: Message thread identifier
properties:
parent:
type: string
xml:
attribute: true
id:
type: string
xml:
text: true
show:
description: indicator of availability, ie away or not
type: string
enum:
- away
- chat
- dnd
- xa
status:
description: Textual status message.
type: string
priority:
description: Presence priority
type: integer
maximum: 127
minimum: -128
state:
description: Chat state notifications, e.g. "is typing..."
type: string
xml:
namespace: http://jabber.org/protocol/chatstates
x_name_is_value: true
enum:
- active
- inactive
- gone
- composing
- paused
example: composing
nick:
type: string
description: Nickname of the sender
xml:
name: nick
namespace: http://jabber.org/protocol/nick
delay:
type: string
format: date-time
description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082
format.
xml:
name: delay
namespace: urn:xmpp:delay
x_single_attribute: stamp
replace:
type: string
description: ID of message being replaced (e.g. for corrections)
xml:
name: replace
namespace: urn:xmpp:message-correct:0
x_single_attribute: id
join:
description: For joining Multi-User-Chats
type: boolean
enum:
- true
invite:
type: object
description: Invite to a group chat
required:
- jid
xml:
name: x
namespace: jabber:x:conference
properties:
jid:
type: string
description: Address of the group chat
format: xmpp-jid
xml:
attribute: true
reason:
type: string
description: Optional message by the inviter
xml:
attribute: true
password:
type: string
description: Password for the group chat, if required
xml:
attribute: true
thread:
type: string
xml:
attribute: true
continue:
type: boolean
description: Whether the group chat continues a one-to-one chat
xml:
attribute: true
html:
description: HTML version of 'body'
example: <body><p>Hello!</p></body>
type: string
ping:
description: A ping.
type: boolean
enum:
- true
xml:
name: ping
namespace: urn:xmpp:ping
version:
type: object
description: Software version query
properties:
name:
type: string
example: My Software
version:
type: string
example: 1.0.0
os:
type: string
example: Linux
required:
- name
- version
xml:
name: query
namespace: jabber:iq:version
disco:
description: Discover supported features
oneOf:
- description: A full response
type: object
properties:
features:
description: List of URIs indicating supported features
type: array
items:
type: string
identities:
description: List of abstract identities or types that describe the
entity
type: array
example:
- name: Prosody
type: im
category: server
items:
type: object
properties:
name:
type: string
type:
type: string
category:
type: string
node:
type: string
extensions:
type: object
- description: A query with a node, or an empty response with a node
type: string
- description: Either a query, or an empty response
type: boolean
items:
description: List of references to other entities
oneOf:
- description: List of items referenced
type: array
items:
properties:
jid:
type: string
description: Address of item
node:
type: string
name:
type: string
description: Descriptive name
required:
- jid
type: object
- type: string
description: A query with a node, or an empty reply list with a node
- description: An items query or empty list
type: boolean
enum:
- true
command:
description: Ad-hoc commands.
oneOf:
- type: object
properties:
data:
$ref: '#/components/schemas/formdata'
action:
type: string
note:
type: object
properties:
text:
type: string
type:
type: string
enum:
- info
- warn
- error
form:
$ref: '#/components/schemas/dataform'
sessionid:
type: string
status:
type: string
node:
type: string
actions:
type: object
properties:
complete:
type: boolean
prev:
type: boolean
next:
type: boolean
execute:
type: string
- type: string
description: Call a command by 'node' id, without arguments
oob:
type: object
description: Reference a media file
xml:
name: x
namespace: jabber:x:oob
properties:
url:
type: string
description: URL of the attached media file
example: https://media.example.net/thisfile.jpg
format: uri
desc:
description: Optional description
type: string
payload:
description: A piece of arbitrary JSON with a type field attached
type: object
xml:
name: payload
namespace: urn:xmpp:json-msg:0
required:
- datatype
- data
properties:
data:
example: '{"some":"json"}'
type: object
datatype:
example: urn:example:my-json#payload
type: string
dataform:
description: Data form
type: object
properties:
title:
description: Title of the form
example: TPS Report
type: string
fields:
type: array
items:
description: Form field
type: object
properties:
value:
description: Field value
oneOf:
- type: string
- type: array
items:
type: string
type:
description: Type of form field
type: string
label:
description: Descriptive label for the field
type: string
desc:
description: Longer description, i.e. that would go in a tooltip
type: string
required:
description: Whether the field must be included in the form
type: boolean
var:
description: Internal name of the field
type: string
type:
type: string
enum:
- form
- submit
- cancel
- result
instructions:
type: string
formdata:
description: Simplified data form carrying only values
type: object
additionalProperties:
oneOf:
- type: string
- type: array
items:
type: string
stats:
description: Statistics
type: array
xml:
name: query
namespace: http://jabber.org/protocol/stats
wrapped: true
items:
type: object
properties:
name:
type: string
xml:
attribute: true
unit:
type: string
xml:
attribute: true
value:
type: string
xml:
attribute: true
caps:
type: object
xml:
name: c
namespace: http://jabber.org/protocol/caps
properties:
ver:
type: string
xml:
attribute: true
hash:
type: string
xml:
attribute: true
node:
type: string
xml:
attribute: true
ext:
type: string
xml:
attribute: true
error:
description: Description of something gone wrong. See the Stanza Errors section in RFC 6120.
type: object
properties:
type:
description: General category of error
type: string
enum:
- auth
- cancel
- continue
- modify
- wait
condition:
description: Specific error condition.
type: string
# enum: [ full list available in RFC 6120 ]
code:
description: Legacy numeric error code. Similar to HTTP status codes.
type: integer
text:
description: Description of error intended for human eyes.
type: string
securitySchemes:
token:
description: Tokens from mod_http_oauth2.
scheme: Bearer
type: http
basic:
description: Use JID as username.
scheme: Basic
type: http
requestBodies:
common:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/stanza'
application/xmpp+xml:
schema:
description: Single XMPP stanza in XML format.
application/x-www-form-urlencoded:
schema:
description: A subset of the JSON schema, only top level string fields.
responses:
success:
description: The stanza was sent and returned a response.
content:
application/json:
schema:
$ref: '#/components/schemas/stanza'
application/xmpp+xml:
schema:
description: Single XMPP stanza in XML format.
example: <message><body>Hello</body></message>
application/x-www-form-urlencoded:
schema:
description: A subset of the JSON schema, only top level string fields.
example: body=Hello
text/plain:
schema:
description: Plain text response used as message body.
example: Hello
type: string
sent:
description: The stanza was sent without problem, and without response,
so an empty reply.
parameters:
to:
name: to
in: path
required: true
schema:
$ref: '#/components/schemas/to'
kind:
name: kind
in: path
required: true
schema:
$ref: '#/components/schemas/kind'
type:
name: type
in: path
required: true
schema:
$ref: '#/components/schemas/type'
...