# HG changeset patch # User Kim Alvefur # Date 1616527664 -3600 # Node ID fd15e7f00ff5641b886d7fd30263b43f1988e1d9 # Parent 9a6aaba3d5efd6f887c87b82dd09c7fc45b2b5e2 mod_rest: Move openapi spec into res/ dir to get it included in rocks diff -r 9a6aaba3d5ef -r fd15e7f00ff5 mod_rest/apidemo.lib.lua --- a/mod_rest/apidemo.lib.lua Tue Mar 23 20:25:21 2021 +0100 +++ b/mod_rest/apidemo.lib.lua Tue Mar 23 20:27:44 2021 +0100 @@ -20,7 +20,7 @@ end do - local f = module:load_resource("openapi.yaml"); + local f = module:load_resource("res/openapi.yaml"); _M.schema = { headers = { content_type = "text/x-yaml"; diff -r 9a6aaba3d5ef -r fd15e7f00ff5 mod_rest/openapi.yaml --- a/mod_rest/openapi.yaml Tue Mar 23 20:25:21 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,651 +0,0 @@ ---- -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/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 - - properties: - kind: - $ref: '#/components/schemas/kind' - type: - $ref: '#/components/schemas/type' - 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' - - show: - $ref: '#/components/schemas/show' - status: - $ref: '#/components/schemas/status' - priority: - $ref: '#/components/schemas/priority' - - state: - $ref: '#/components/schemas/state' - nick: - $ref: '#/components/schemas/nick' - delay: - $ref: '#/components/schemas/delay' - replace: - $ref: '#/components/schemas/replace' - - join: - $ref: '#/components/schemas/join' - - html: - $ref: '#/components/schemas/html' - - 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' - - oob_url: - $ref: '#/components/schemas/oob_url' - payload: - $ref: '#/components/schemas/payload' - dataform: - $ref: '#/components/schemas/dataform' - formdata: - $ref: '#/components/schemas/formdata' - stats: - $ref: '#/components/schemas/stats' - 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 - type: string - - 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: string - - state: - description: Chat state notifications, e.g. "is typing..." - type: string - enum: - - active - - inactive - - gone - - composing - - paused - example: composing - - nick: - type: string - description: Nickname of the sender - - delay: - type: string - description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 - format. - - replace: - type: string - description: ID of message being replaced (e.g. for corrections) - - join: - description: For joining Multi-User-Chats - type: boolean - enum: - - 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_url: - description: URL of an attached media file. - example: https://media.example.net/thisfile.jpg - type: string - - payload: - description: A piece of arbitrary JSON with a type field attached - type: object - 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 - items: - type: object - properties: - name: - type: string - unit: - type: string - value: - type: string - - 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' - -... diff -r 9a6aaba3d5ef -r fd15e7f00ff5 mod_rest/res/openapi.yaml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_rest/res/openapi.yaml Tue Mar 23 20:27:44 2021 +0100 @@ -0,0 +1,651 @@ +--- +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/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 + + properties: + kind: + $ref: '#/components/schemas/kind' + type: + $ref: '#/components/schemas/type' + 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' + + show: + $ref: '#/components/schemas/show' + status: + $ref: '#/components/schemas/status' + priority: + $ref: '#/components/schemas/priority' + + state: + $ref: '#/components/schemas/state' + nick: + $ref: '#/components/schemas/nick' + delay: + $ref: '#/components/schemas/delay' + replace: + $ref: '#/components/schemas/replace' + + join: + $ref: '#/components/schemas/join' + + html: + $ref: '#/components/schemas/html' + + 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' + + oob_url: + $ref: '#/components/schemas/oob_url' + payload: + $ref: '#/components/schemas/payload' + dataform: + $ref: '#/components/schemas/dataform' + formdata: + $ref: '#/components/schemas/formdata' + stats: + $ref: '#/components/schemas/stats' + 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 + type: string + + 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: string + + state: + description: Chat state notifications, e.g. "is typing..." + type: string + enum: + - active + - inactive + - gone + - composing + - paused + example: composing + + nick: + type: string + description: Nickname of the sender + + delay: + type: string + description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 + format. + + replace: + type: string + description: ID of message being replaced (e.g. for corrections) + + join: + description: For joining Multi-User-Chats + type: boolean + enum: + - 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_url: + description: URL of an attached media file. + example: https://media.example.net/thisfile.jpg + type: string + + payload: + description: A piece of arbitrary JSON with a type field attached + type: object + 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 + items: + type: object + properties: + name: + type: string + unit: + type: string + value: + type: string + + 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' + +...