view mod_rest/res/openapi.yaml @ 4876:0f5f2d4475b9

mod_http_xep227: Add support for import via APIs rather than direct store manipulation In particular this transitions PEP nodes and data to be imported via mod_pep's APIs, fixing issues with importing at runtime while PEP data may already be live in RAM. Next obvious candidate for this approach is rosters, so clients get immediate roster pushes and other special handling (such as emitting subscribes to reach the desired subscription state).
author Matthew Wild <mwild1@gmail.com>
date Tue, 18 Jan 2022 17:01:18 +0000
parents 75543146e94e
children 52522c71ad1a
line wrap: on
line source

---
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'

        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: <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

    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

    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'

...