--- 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' /rest/extdisco/{to}: get: tags: - query summary: Query a message archive security: - basic: [] - token: [] parameters: - $ref: '#/components/parameters/to' - name: type in: query schema: type: string example: stun 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 xml: attribute: true 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' reactions: $ref: '#/components/schemas/reactions' occupant_id: $ref: '#/components/schemas/occupant_id' attach_to: $ref: '#/components/schemas/attach_to' fallback: $ref: '#/components/schemas/fallback' stanza_ids: $ref: '#/components/schemas/stanza_ids' reference: $ref: '#/components/schemas/reference' markable: $ref: '#/components/schemas/markable' displayed: $ref: '#/components/schemas/displayed' error: $ref: '#/components/schemas/error' presence: type: object properties: kind: description: Which kind of stanza type: string enum: - presence type: type: string enum: - available - unavailable - subscribe - subscribed - unsubscribe - unsubscribed - error xml: attribute: true 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' vcard_update: $ref: '#/components/schemas/vcard_update' idle_since: $ref: '#/components/schemas/idle_since' 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 xml: attribute: true 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' lastactivity: $ref: '#/components/schemas/lastactivity' 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' gateway: $ref: '#/components/schemas/gateway' register: $ref: '#/components/schemas/register' extdisco: $ref: '#/components/schemas/extdisco' upload_request: $ref: '#/components/schemas/upload_request' upload_slot: $ref: '#/components/schemas/upload_slot' 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 xml: attribute: true to: description: recipient example: alice@example.com type: string xml: attribute: true from: description: the sender example: bob@localhost.example type: string xml: attribute: true id: description: Reasonably unique id. mod_rest generates one if left out. type: string xml: attribute: true lang: description: Language code example: en xml: prefix: xml attribute: true 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:

Hello!

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 lastactivity: type: object xml: name: query namespace: jabber:iq:last properties: seconds: type: integer minimum: 0 xml: attribute: true status: type: string xml: text: 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 vcard_update: type: object xml: name: x namespace: vcard-temp:x:update properties: photo: type: string example: adc83b19e793491b1c6ea0fd8b46cd9f32e592fc reactions: type: object xml: namespace: urn:xmpp:reactions:0 properties: id: type: string xml: attribute: true reactions: type: array items: xml: name: reaction type: string xml: wrapped: false name: reactions occupant_id: type: string xml: namespace: urn:xmpp:occupant-id:0 x_single_attribute: id name: occupant-id attach_to: type: string xml: namespace: urn:xmpp:message-attaching:1 x_single_attribute: id name: attach-to fallback: type: boolean xml: namespace: urn:xmpp:fallback:0 x_name_is_value: true name: fallback stanza_ids: type: array items: type: object required: - id - by xml: namespace: urn:xmpp:sid:0 name: stanza-id properties: id: xml: attribute: true type: string by: xml: attribute: true format: xmpp-jid type: string reference: type: object xml: namespace: urn:xmpp:reference:0 properties: end: minimum: 0 xml: attribute: true type: integer uri: xml: attribute: true format: uri type: string begin: minimum: 0 xml: attribute: true type: integer type: xml: attribute: true type: string required: - type - uri markable: type: boolean xml: namespace: urn:xmpp:chat-markers:0 x_name_is_value: true displayed: type: string description: Message ID of a message that has been displayed xml: namespace: urn:xmpp:chat-markers:0 idle_since: type: string xml: namespace: urn:xmpp:idle:1 x_single_attribute: since name: idle format: date-time gateway: type: object xml: namespace: jabber:iq:gateway name: query properties: desc: type: string prompt: type: string jid: type: string extdisco: type: object xml: namespace: urn:xmpp:extdisco:2 name: services properties: type: xml: attribute: true type: string services: items: type: object xml: name: service required: - type - host properties: transport: xml: attribute: true type: string type: xml: attribute: true type: string port: xml: attribute: true type: integer host: xml: attribute: true type: string expires: xml: attribute: true format: datetime type: string username: xml: attribute: true type: string password: xml: attribute: true type: string restricted: xml: attribute: true type: boolean name: xml: attribute: true type: string type: array register: type: object description: Register with a service xml: namespace: jabber:iq:register name: query properties: nick: type: string misc: type: string password: type: string date: type: string address: type: string key: type: string text: type: string url: type: string zip: type: string phone: type: string last: type: string email: type: string remove: xml: x_name_is_value: true type: boolean city: type: string registered: xml: x_name_is_value: true type: boolean first: type: string state: type: string instructions: type: string username: type: string name: type: string required: - username - password upload_slot: type: object xml: name: slot namespace: urn:xmpp:http:upload:0 properties: put: type: object properties: url: type: string format: uri xml: attribute: true headers: type: array items: type: object required: - name - value xml: name: header properties: name: type: string enum: - Authorization - Cookie - Expires xml: attribute: true value: type: string xml: text: true get: type: object properties: url: type: string format: uri xml: attribute: true upload_request: type: object required: - filename - size xml: name: request namespace: urn:xmpp:http:upload:0 properties: filename: type: string xml: attribute: true content-type: xml: attribute: true name: content-type size: type: integer 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: Hello 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' ...