api/v4/source/sharedchannels.yaml - master - yakobsonsa/erchat

api/v4/source/sharedchannels.yaml
313 строк10 KB
catalintomai
MM-64531: [Shared Channels] Users on different remote servers should not communicate unless the remotes have established secure connection. (#30985)
15 июл 2025, 10:30
Не верифицирован
15 июл 2025, 10:3069e483f
  "/api/v4/sharedchannels/{team_id}":
    get:
      tags:
        - shared channels
      summary: Get all shared channels for team.
      description: |
        Get all shared channels for a team.

        __Minimum server version__: 5.50

        ##### Permissions
        Must be authenticated.
      operationId: GetAllSharedChannels
      parameters:
        - name: team_id
          in: path
          description: Team Id
          required: true
          schema:
            type: string
        - name: page
          description: The page to select.
          in: query
          schema:
            type: integer
            default: 0
        - name: per_page
          description: The number of sharedchannels per page.
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Shared channels fetch successful. Result may be empty.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SharedChannel"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/remotecluster/{remote_id}/sharedchannelremotes":
    get:
      tags:
        - shared channels
      summary: Get shared channel remotes by remote cluster.
      description: |
        Get a list of the channels shared with a given remote cluster
        and their status.

        ##### Permissions
        `manage_secure_connections`
      operationId: GetSharedChannelRemotesByRemoteCluster
      parameters:
        - name: remote_id
          in: path
          description: The remote cluster GUID
          required: true
          schema:
            type: string
        - name: include_unconfirmed
          in: query
          description: Include those Shared channel remotes that are unconfirmed
          schema:
            type: boolean
        - name: exclude_confirmed
          in: query
          description: Show only those Shared channel remotes that are not confirmed yet
          schema:
            type: boolean
        - name: exclude_home
          in: query
          description: Show only those Shared channel remotes that were shared with this server
          schema:
            type: boolean
        - name: exclude_remote
          in: query
          description: Show only those Shared channel remotes that were shared from this server
          schema:
            type: boolean
        - name: include_deleted
          in: query
          description: Include those Shared channel remotes that have been deleted
          schema:
            type: boolean
        - name: page
          in: query
          description: The page to select
          schema:
            type: integer
        - name: per_page
          in: query
          description: The number of shared channels per page
          schema:
            type: integer
      responses:
        "200":
          description: Shared channel remotes fetch successful. Result might be empty.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SharedChannelRemote"

        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/sharedchannels/remote_info/{remote_id}":
    get:
      tags:
        - shared channels
      summary: Get remote cluster info by ID for user.
      description: |
        Get remote cluster info based on remoteId.

        __Minimum server version__: 5.50

        ##### Permissions
        Must be authenticated and user must belong to at least one channel shared with the remote cluster.
      operationId: GetRemoteClusterInfo
      parameters:
        - name: remote_id
          in: path
          description: Remote Cluster GUID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Remote cluster info retrieval successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteClusterInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  "/api/v4/remotecluster/{remote_id}/channels/{channel_id}/invite":
    post:
      tags:
        - shared channels
      summary: Invites a remote cluster to a channel.
      description: |
        Invites a remote cluster to a channel, sharing the channel if
        needed. If the remote cluster was already invited to the
        channel, calling this endpoint will have no effect.

        ##### Permissions
        `manage_shared_channels`
      operationId: InviteRemoteClusterToChannel
      parameters:
        - name: remote_id
          in: path
          description: The remote cluster GUID
          required: true
          schema:
            type: string
        - name: channel_id
          in: path
          description: The channel GUID to invite the remote cluster to
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Remote cluster invited successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusOK"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/remotecluster/{remote_id}/channels/{channel_id}/uninvite":
    post:
      tags:
        - shared channels
      summary: Uninvites a remote cluster to a channel.
      description: |
        Stops sharing a channel with a remote cluster. If the channel
        was not shared with the remote, calling this endpoint will
        have no effect.

        ##### Permissions
        `manage_shared_channels`
      operationId: UninviteRemoteClusterToChannel
      parameters:
        - name: remote_id
          in: path
          description: The remote cluster GUID
          required: true
          schema:
            type: string
        - name: channel_id
          in: path
          description: The channel GUID to uninvite the remote cluster to
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Remote cluster uninvited successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusOK"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/sharedchannels/{channel_id}/remotes":
    get:
      tags:
        - shared channels
      summary: Get remote clusters for a shared channel
      description: |
        Gets the remote clusters information for a shared channel.
        
        __Minimum server version__: 10.11
        
        ##### Permissions
        Must be authenticated and have the `read_channel` permission for the channel.
      operationId: GetSharedChannelRemotes
      parameters:
        - name: channel_id
          in: path
          description: Channel GUID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Remote clusters retrieval successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RemoteClusterInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  "/api/v4/sharedchannels/users/{user_id}/can_dm/{other_user_id}":
    get:
      tags:
        - shared channels
      summary: Check if user can DM another user in shared channels context
      description: |
        Checks if a user can send direct messages to another user, considering shared channel restrictions.
        This is specifically for shared channels where DMs require direct connections between clusters.
        
        __Minimum server version__: 10.11
        
        ##### Permissions
        Must be authenticated and have permission to view the user.
      operationId: CanUserDirectMessage
      parameters:
        - name: user_id
          in: path
          description: User GUID
          required: true
          schema:
            type: string
        - name: other_user_id
          in: path
          description: Other user GUID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: DM permission check successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  can_dm:
                    type: boolean
                    description: Whether the user can send DMs to the other user
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"