corteza/messaging/rest.yaml

---

# This is direct conversion from old api/*/spec.json files
# using https://www.json2yaml.com/
#
# Next step: swagger.

endpoints:
- title: Commands
  entrypoint: commands
  path: "/commands"
  authentication: []
  apis:
  - name: list
    path: "/"
    method: GET
    title: List of available commands
- title: Status
  entrypoint: status
  path: "/status"
  authentication: []
  apis:
  - name: list
    path: "/"
    method: GET
    title: See all current statuses
  - name: set
    path: "/"
    method: POST
    title: Set user's status
    parameters:
      post:
      - type: string
        name: icon
        required: false
        title: Status icon
      - type: string
        name: message
        required: false
        title: Status message
      - type: string
        name: expires
        required: false
        title: 'Clear status when it expires (eg: when-active, afternoon, tomorrow
          1h, 30m, 1 PM, 2019-05-20)'
  - name: delete
    path: "/"
    method: DELETE
    title: Clear status
- name: activity
  path: "/activity"
  entrypoint: activity
  title: User activity
  authentication: []
  apis:
  - name: send
    method: POST
    title: Sends user's activity to all subscribers; globally or per channel/message.
    path: "/"
    parameters:
      post:
      - name: channelID
        type: uint64
        required: false
        title: Channel ID, if set, activity will be send only to subscribed users
      - name: messageID
        type: uint64
        required: false
        title: Message ID, if set, channelID must be set as well
      - name: kind
        type: string
        required: true
        title: Arbitrary string
- title: Channels
  description: A channel is a representation of a sequence of messages. It has meta
    data like channel subject. Channels may be public, private or group.
  entrypoint: channel
  path: "/channels"
  authentication:
  - Client ID
  - Session ID
  imports:
    - github.com/cortezaproject/corteza-server/messaging/types
  apis:
  - name: list
    method: GET
    title: List channels
    path: "/"
    parameters:
      get:
      - type: string
        name: query
        required: false
        title: Search query
  - name: create
    method: POST
    title: Create new channel
    path: "/"
    parameters:
      post:
      - type: string
        name: name
        required: false
        title: Name of Channel
      - type: string
        name: topic
        required: false
        title: Subject of Channel
      - type: string
        name: type
        required: false
        title: Channel type
      - type: types.ChannelMembershipPolicy
        name: membershipPolicy
        required: false
        title: 'Membership policy (eg: featured, forced)?'
      - type: "[]string"
        name: members
        required: false
        title: Initial members of the channel
  - name: update
    method: PUT
    path: "/{channelID}"
    title: Update channel details
    parameters:
      path:
      - type: uint64
        name: channelID
        required: true
        title: Channel ID
      post:
      - type: string
        name: name
        required: false
        title: Name of Channel
      - type: string
        name: topic
        required: false
        title: Subject of Channel
      - type: types.ChannelMembershipPolicy
        name: membershipPolicy
        required: false
        title: 'Membership policy (eg: featured, forced)?'
      - type: string
        name: type
        required: false
        title: Channel type
      - type: uint64
        name: organisationID
        required: false
        title: Move channel to different organisation
  - name: state
    method: PUT
    path: "/{channelID}/state"
    title: Update channel state
    parameters:
      path:
      - type: uint64
        name: channelID
        required: true
        title: Channel ID
      post:
      - type: string
        name: state
        required: true
        title: 'Valid values: delete, undelete, archive, unarchive'
  - name: setFlag
    method: PUT
    path: "/{channelID}/flag"
    title: Update channel membership flag
    parameters:
      path:
      - type: uint64
        name: channelID
        required: true
        title: Channel ID
      post:
      - type: string
        name: flag
        required: true
        title: 'Valid values: pinned, hidden, ignored'
  - name: removeFlag
    method: DELETE
    path: "/{channelID}/flag"
    title: Remove channel membership flag
    parameters:
      path:
      - type: uint64
        name: channelID
        required: true
        title: Channel ID
  - name: read
    method: GET
    path: "/{channelID}"
    title: Read channel details
    parameters:
      path:
      - type: uint64
        name: channelID
        required: true
        title: Channel ID
  - name: members
    method: GET
    path: "/{channelID}/members"
    title: List channel members
    parameters:
      path:
      - name: channelID
        type: uint64
        required: true
        title: Channel ID
  - name: join
    method: PUT
    path: "/{channelID}/members/{userID}"
    title: Join channel
    parameters:
      path:
      - name: channelID
        type: uint64
        required: true
        title: Channel ID
      - name: userID
        type: uint64
        required: false
        title: Member ID
  - name: part
    method: DELETE
    path: "/{channelID}/members/{userID}"
    title: Remove member from channel
    parameters:
      path:
      - name: channelID
        type: uint64
        required: true
        title: Channel ID
      - name: userID
        type: uint64
        required: false
        title: Member ID
  - name: invite
    method: POST
    path: "/{channelID}/invite"
    title: Join channel
    parameters:
      path:
      - name: channelID
        type: uint64
        required: true
        title: Channel ID
      post:
      - name: userID
        type: "[]string"
        required: false
        title: User ID
  - name: attach
    path: "/{channelID}/attach"
    method: POST
    title: Attach file to channel
    parameters:
      path:
      - name: channelID
        type: uint64
        required: true
        title: Channel ID
      post:
      - name: replyTo
        type: uint64
        required: false
        title: Upload as a reply
      - name: upload
        type: "*multipart.FileHeader"
        required: true
        title: File to upload
- title: Messages
  path: "/channels/{channelID}/messages"
  parameters:
    path:
    - name: channelID
      type: uint64
      required: true
      title: Channel ID
  entrypoint: message
  authentication:
  - Client ID
  - Session ID
  apis:
  - name: create
    path: "/"
    method: POST
    title: Post new message to the channel
    parameters:
      post:
      - type: string
        name: message
        required: true
        sensitive: true
        title: Message contents (markdown)
  - name: executeCommand
    path: "/command/{command}/exec"
    method: POST
    title: Execute command
    parameters:
      path:
      - name: command
        type: string
        required: true
        title: Command to be executed
      post:
      - type: string
        name: input
        required: false
        title: Arbitrary command input
      - type: "[]string"
        name: params
        required: false
        title: Command parameters
  - name: markAsRead
    path: "/mark-as-read"
    method: GET
    title: Manages read/unread messages in a channel or a thread
    parameters:
      path: []
      get:
      - type: uint64
        name: threadID
        required: false
        title: 'ID of thread (messageID) '
      - type: uint64
        name: lastReadMessageID
        required: false
        title: ID of the last read message
  - name: edit
    path: "/{messageID}"
    method: PUT
    title: Edit existing message
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
      post:
      - type: string
        name: message
        required: true
        sensitive: true
        title: Message contents (markdown)
  - name: delete
    path: "/{messageID}"
    method: DELETE
    title: Delete existing message
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
  - name: replyCreate
    path: "/{messageID}/replies"
    method: POST
    title: Reply to a message
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
      post:
      - type: string
        name: message
        required: true
        sensitive: true
        title: Message contents (markdown)
  - name: pinCreate
    path: "/{messageID}/pin"
    method: POST
    title: Pin message to channel (public bookmark)
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
  - name: pinRemove
    path: "/{messageID}/pin"
    method: DELETE
    title: Pin message to channel (public bookmark)
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
  - name: bookmarkCreate
    path: "/{messageID}/bookmark"
    method: POST
    title: Bookmark a message (private bookmark)
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
  - name: bookmarkRemove
    path: "/{messageID}/bookmark"
    method: DELETE
    title: Remove boomark from message (private bookmark)
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
  - name: reactionCreate
    path: "/{messageID}/reaction/{reaction}"
    method: POST
    title: React to a message
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
      - name: reaction
        type: string
        required: true
        title: Reaction
  - name: reactionRemove
    path: "/{messageID}/reaction/{reaction}"
    method: DELETE
    title: Delete reaction from a message
    parameters:
      path:
      - name: messageID
        type: uint64
        required: true
        title: Message ID
      - name: reaction
        type: string
        required: true
        title: Reaction
- title: Attachments
  path: "/attachment/{attachmentID}"
  parameters:
    path:
    - name: attachmentID
      type: uint64
      required: true
      title: Attachment ID
    get:
    - type: string
      name: sign
      required: true
      title: Signature
    - type: uint64
      name: userID
      required: true
      title: User ID
  entrypoint: attachment
  authentication:
  - Client ID
  - Session ID
  apis:
  - name: original
    path: "/original/{name}"
    method: GET
    title: Serves attached file
    parameters:
      path:
      - name: name
        type: string
        required: true
        title: File name
      get:
      - type: bool
        name: download
        required: false
        title: Force file download
  - name: preview
    path: "/preview.{ext}"
    method: GET
    title: Serves preview of an attached file
    parameters:
      path:
      - name: ext
        type: string
        required: true
        title: Preview extension/format
- name: search
  entrypoint: search
  authentication:
  - Client ID
  - Session ID
  path: "/search"
  method: GET
  title: Search entry point
  parameters:
    get:
    - name: query
      type: string
      required: false
      title: Search query
  apis:
  - method: GET
    name: messages
    path: "/messages"
    title: Search for messages
    parameters:
      get:
      - name: channelID
        type: "[]string"
        required: false
        title: Filter by channels
      - name: afterMessageID
        type: uint64
        required: false
        title: ID of the first message in the list (exclusive)
      - name: beforeMessageID
        type: uint64
        required: false
        title: ID of the last message in the list (exclusive)
      - name: fromMessageID
        type: uint64
        required: false
        title: ID of the first message in the list (inclusive)
      - name: toMessageID
        type: uint64
        required: false
        title: ID of the last message the list (inclusive)
      - name: threadID
        type: "[]string"
        required: false
        title: Filter by thread message ID
      - name: userID
        type: "[]string"
        required: false
        title: Filter by one or more user
      - name: type
        type: "[]string"
        required: false
        title: Filter by message type (text, inlineImage, attachment, ...)
      - name: pinnedOnly
        type: bool
        required: false
        title: Return only pinned messages
      - name: bookmarkedOnly
        type: bool
        required: false
        title: Only bookmarked messages
      - name: limit
        type: uint
        required: false
        title: Max number of messages
  - method: GET
    name: threads
    path: "/threads"
    title: Search for threads
    parameters:
      get:
      - name: channelID
        type: "[]string"
        required: false
        title: Filter by channels
      - name: limit
        type: uint
        required: false
        title: Max number of messages
- title: Permissions
  entrypoint: permissions
  path: "/permissions"
  authentication:
  - Client ID
  - Session ID
  imports:
    - github.com/cortezaproject/corteza-server/pkg/rbac
  apis:
  - name: list
    path: "/"
    method: GET
    title: Retrieve defined permissions
  - name: effective
    path: "/effective"
    method: GET
    title: Effective rules for current user
    parameters:
      get:
      - name: resource
        type: string
        required: false
        title: Show only rules for a specific resource
  - name: read
    path: "/{roleID}/rules"
    method: GET
    title: Retrieve role permissions
    parameters:
      path:
      - name: roleID
        type: uint64
        required: true
        title: Role ID
  - name: delete
    path: "/{roleID}/rules"
    method: DELETE
    title: Remove all defined role permissions
    parameters:
      path:
      - name: roleID
        type: uint64
        required: true
        title: Role ID
  - name: update
    path: "/{roleID}/rules"
    method: PATCH
    title: Update permission settings
    parameters:
      path:
      - name: roleID
        type: uint64
        required: true
        title: Role ID
      post:
      - name: rules
        type: rbac.RuleSet
        required: true
        title: List of permission rules to set