Mercurial > prosody-modules

view mod_rest/openapi.yaml @ 4477:8df6cc648963

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add more REST-looking way to send stanzas Example: POST /rest/message/chat/juliet@example.net { body: "Hello" } Becomes equivalent to POST /rest { kind: "message", type: "chat", to: "juliet@example.net", body: "Hello" } Sending messages as plain/text also becomes more convenient. IQ stazas are still weird, but we'll do something special for those.
author Kim Alvefur <zash@zash.se>
date Sun, 28 Feb 2021 19:25:45 +0100
parents 125279f4a5b8
children 7ab0c423688a
line wrap: on
line source

---
openapi: 3.0.1
info:
  title: mod_rest API
  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.
  version: 0.1.0
  license:
    name: MIT
paths:
  /rest:
    post:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              description: A subset of the JSON schema, only top level string fields.
          application/xmpp+xml:
            schema:
              description: Single XMPP stanza in XML format.
          application/json:
            schema:
              $ref: '#/components/schemas/stanza'
      security:
        - basic: []
        - token: []
      summary: Send stanzas and receive responses. Webhooks work the same way.
      responses:
        200:
          content:
            text/plain:
              schema:
                description: Plain text response used as message body.
                example: Hello
                type: string
            application/x-www-form-urlencoded:
              schema:
                description: A subset of the JSON schema, only top level string fields.
                example: body=Hello
            application/xmpp+xml:
              schema:
                description: Single XMPP stanza in XML format.
                example: <message><body>Hello</body></message>
            application/json:
              schema:
                $ref: '#/components/schemas/stanza'
          description: The stanza was sent and returned a response.
        401:
          description: No credentials or auth token were provided.
        202:
          description: The stanza was sent without problem, and without response,
            so an empty reply.
        403:
          description: Provided credentials or token not accepted.
        400:
          description: There was a syntax problem in the payload.
        422:
          description: The was a problem with the format (but not the syntax) of the
            payload.
        415:
          description: Unsupported mediatype.
  /rest/{kind}/{type}/{to}:
    post:
      responses:
        200:
          description: Okay
      security:
      - basic: []
      - token: []
      summary: Even more RESTful mapping.
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/kind'
      - name: type
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type'
      - name: to
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/to'
components:
  schemas:
    stanza:
      properties:
        delay:
          $ref: '#/components/schemas/delay'
        state:
          $ref: '#/components/schemas/state'
        type:
          $ref: '#/components/schemas/type'
        status:
          $ref: '#/components/schemas/status'
        id:
          $ref: '#/components/schemas/id'
        replace:
          $ref: '#/components/schemas/replace'
        from:
          $ref: '#/components/schemas/from'
        body:
          $ref: '#/components/schemas/body'
        kind:
          $ref: '#/components/schemas/kind'
        show:
          $ref: '#/components/schemas/show'
        stats:
          $ref: '#/components/schemas/stats'
        priority:
          $ref: '#/components/schemas/priority'
        nick:
          $ref: '#/components/schemas/nick'
        to:
          $ref: '#/components/schemas/to'
        ping:
          $ref: '#/components/schemas/ping'
        subject:
          $ref: '#/components/schemas/subject'
        lang:
          $ref: '#/components/schemas/lang'
        join:
          $ref: '#/components/schemas/join'
        html:
          $ref: '#/components/schemas/html'
        dataform:
          $ref: '#/components/schemas/dataform'
        version:
          $ref: '#/components/schemas/version'
        payload:
          $ref: '#/components/schemas/payload'
        disco:
          $ref: '#/components/schemas/disco'
        oob_url:
          $ref: '#/components/schemas/oob_url'
        items:
          $ref: '#/components/schemas/items'
        formdata:
          $ref: '#/components/schemas/formdata'
        thread:
          $ref: '#/components/schemas/thread'
        command:
          $ref: '#/components/schemas/command'
      type: object
      example:
        body: Hello
        type: chat
        kind: message
        to: alice@example.com
        state: active
    delay:
      type: string
      description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082
        format.
    state:
      enum:
      - active
      - inactive
      - gone
      - composing
      - paused
      description: Chat state notifications, e.g. "is typing..."
      type: string
      example: composing
    thread:
      type: string
      description: Message thread identifier
    status:
      type: string
      description: Textual status message.
    id:
      type: string
      description: Reasonably unique id. mod_rest generates one if left out.
    replace:
      type: string
      description: ID of message being replaced (e.g. for corrections)
    from:
      description: the sender
      type: string
      example: bob@localhost.example
    body:
      description: Human-readable chat message
      type: string
      example: Hello, World!
    command:
      oneOf:
      - type: string
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/stanza/properties/formdata'
          action:
            type: string
          note:
            type: object
            properties:
              text:
                type: string
              type:
                type: string
                enum:
                - info
                - warn
                - error
          form:
            $ref: '#/components/schemas/stanza/properties/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
      description: Ad-hoc commands.
    show:
      description: indicator of availability, ie away or not
      type: string
      enum:
      - away
      - chat
      - dnd
      - xa
    stats:
      description: Statistics
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          unit:
            type: string
          value:
            type: string
    priority:
      type: string
      description: presence priority
    kind:
      description: Which kind of stanza
      type: string
      enum:
      - message
      - presence
      - iq
    to:
      description: recipient
      type: string
      example: alice@example.com
    type:
      description: Stanza type
      type: string
      enum:
      - chat
      - normal
      - headline
      - groupchat
      - get
      - set
      - result
      - available
      - unavailable
      - subscribe
      - subscribed
      - unsubscribe
      - unsubscribed
    lang:
      description: Language code
      type: string
      example: en
    formdata:
      additionalProperties:
        oneOf:
        - type: string
        - type: array
          items:
            type: string
      type: object
      description: Simplified data form
    join:
      description: For joining Multi-User-Chats
      type: boolean
      enum:
      - true
    dataform:
      properties:
        title:
          type: string
        fields:
          type: array
          items:
            type: object
            properties:
              value:
                oneOf:
                - type: string
                - type: array
                  items:
                    type: string
              type:
                type: string
              label:
                type: string
              desc:
                type: string
              required:
                type: boolean
              var:
                type: string
        type:
          type: string
          enum:
          - form
          - submit
          - cancel
          - result
        instructions:
          type: string
      description: Data form
      type: object
    items:
      oneOf:
      - description: An items query or empty list
        type: boolean
        enum:
        - true
      - type: string
        description: A query with a node, or an empty reply list with a node
      - 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
      description: List of references to other entities
    version:
      oneOf:
      - type: boolean
      - properties:
          version:
            type: string
          name:
            type: string
          os:
            type: string
        required:
        - name
        - version
        type: object
      description: Software version query
    payload:
      required:
        - datatype
        - data
      properties:
        data:
          type: object
        datatype:
          type: string
      description: A piece of arbitrary JSON with a type field attached
      type: object
    disco:
      oneOf:
      - type: boolean
        description: Either a query, or an empty response
      - type: string
        description: A query with a node, or an empty response with a node
      - properties:
          features:
            description: List of URIs indicating supported features
            type: array
            items:
              type: string
          identities:
            items:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                category:
                  type: string
            description: List of abstract identities or types that describe the
              entity
            type: array
            example:
            - name: Prosody
              type: im
              category: server
          node:
            type: string
          extensions:
            type: object
        description: A full response
        type: object
      description: Discover supported features
    oob_url:
      type: string
      description: URL of an attached media file.
    html:
      description: HTML version of 'body'
      type: string
      example: <body><p>Hello!</p></body>
    subject:
      description: Subject of message or group chat
      type: string
      example: Talking about stuff
    ping:
      description: A ping.
      type: boolean
      enum:
      - true
    nick:
      type: string
      description: Nickname of the sender
  securitySchemes:
    token:
      description: Tokens from mod_http_oauth2.
      scheme: Bearer
      type: http
    basic:
      description: Use JID as username.
      scheme: Basic
      type: http
...