openapi: 3.0.1
info:
  title: Message Channel Service API
  version: 1.0.0
servers:
- description: The Message Channel Service API REST endpoint
  url: https://api.uat.btx.fr.banqup.com/core/channel
- description: The Message Channel Service API REST endpoint
  url: https://api.uat.btx.eu.banqup.com/core/channel
paths:
  /v1/sessions/{sessionId}/subscriptions:
    post:
      tags:
      - channel-service
      summary: '[DEPRECATED] Subscribe to events'
      description: Create a subscription for events that honor a given set of filters.
        Deprecated due to rename. Use /v1/eventSources/{sourceId}/subscriptions instead.
      operationId: subscribeToSession
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: "The ID of a session that has already been created.\nThe requested
          subscriptions will be appended to this session.\n"
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
        required: true
      responses:
        '201':
          description: The subscription has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResponse'
        '403':
          description: You do not have access to this session.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: The session ID could not be found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      deprecated: true
  /v1/sessions:
    post:
      tags:
      - channel-service
      summary: '[DEPRECATED] Create a session'
      description: Creates an SSE session and subscribes to messages. Deprecated due
        to rename. Use /v1/eventSources instead.
      operationId: createSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
      responses:
        '201':
          description: "The session has been created.\nYou can now start receiving
            events.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
      deprecated: true
  /v1/eventSources/{sourceId}/subscriptions:
    post:
      tags:
      - channel-service
      summary: Subscribes to events
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Create a subscription for events that honor a given set of filters.
        <br/> Scope: []"
      operationId: subscribe
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sourceId
        in: path
        description: "The ID of an event source that has already been created.\nThe
          requested subscriptions will be appended to this event source.\n"
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
        required: true
      responses:
        '201':
          description: The subscription has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResponse'
        '404':
          description: The event source ID could not be found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: You do not have access to this event source.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
  /v1/eventSources:
    post:
      tags:
      - channel-service
      summary: Create an event source
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Creates an SSE event source and subscribes to it.\nSubscribing is optional
        and only happens when an optional subscription request is provided.\n The
        subscriptions will immediately be activated.\nSubsequent calls to the [**receive-events-endpoint**](../../../docs/foundation/channel/receive-events)
        will immediately deliver all events for those subscriptions.\n <br/> Scope:
        []"
      operationId: createEventSource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageEventSourceRequest'
      responses:
        '201':
          description: The event source has been created. You can now start receiving
            events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageEventSourceResponse'
  /v1/sessions/{sessionId}/events:
    get:
      tags:
      - channel-service
      summary: '[DEPRECATED] Retrieve events'
      description: Opens an SSE stream to start receiving events. Deprecated due to
        rename. Use /v1/eventSources/{sourceId}:receiveEvents instead.
      operationId: getEvents
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: "The ID of an event source that has already been created.\nAll
          events that belong to subscriptions in this session will be returned.\n"
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      - name: Last-Event-ID
        in: header
        description: "In the event a connection is dropped, the client may reconnect
          and set the Last-Event-ID header with the ID of the event it last received.\n
          The channel service will then replay any events that were missed since the
          last seen ID.\nIf possible, the missed events are replayed and the connection
          is resumed.\nIf not, the connection is rejected (HTTP 404) and a new connection
          should be created without a Last-Event-ID.\nThis means that applications
          need to keep into account that some events could be missed.\n"
        required: false
        schema:
          type: string
        example: 41b86461-2c30-4cc6-8892-ea342d2e546b
      responses:
        '404':
          description: The session ID is not found.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerSentEventEvent'
        '200':
          description: The Server Sent Event stream has been opened. You will now
            receive events.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerSentEventEvent'
      deprecated: true
  /v1/eventSources/{sourceId}:receiveEvents:
    get:
      tags:
      - channel-service
      summary: Receive events
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Opens an [**SSE**](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
        stream to start receiving events from an event source. <br/> Scope: []"
      operationId: receiveEvents
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sourceId
        in: path
        description: The id of the event source whose events you'd like to receive.
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      - name: Last-Event-ID
        in: header
        description: "In the event a connection is dropped, the client may reconnect
          and set the Last-Event-ID header with the ID of the event it last received.\n
          The channel service will then replay any events that were missed since the
          last seen ID.\nIf possible, the missed events are replayed and the connection
          is resumed.\nIf not, the connection is rejected and a new connection should
          be created without a Last-Event-ID.\nThis means that applications need to
          keep into account that some events could be missed.\n"
        required: false
        schema:
          type: string
        example: 41b86461-2c30-4cc6-8892-ea342d2e546b
      responses:
        '404':
          description: The sourceId is not found.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerSentEventEvent'
        '200':
          description: The Server Sent Event stream has been opened. You will now
            receive events.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerSentEventEvent'
  /v1/sessions/{sessionId}/subscriptions/{subscriptionId}:
    delete:
      tags:
      - channel-service
      summary: '[DEPRECATED] Unsubscribe from events'
      description: Cancel an existing subscription. After this operation, the event
        stream will no longer contain events for this subscription. Deprecated due
        to rename. Use /eventSources/{sourceId}/subscriptions/{subscriptionId} instead.
      operationId: unsubscribeFromSession
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: "The ID of a session that has already been created.\nThe requested
          subscriptions will be appended to this session.\n"
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      - name: subscriptionId
        in: path
        description: The ID of the subscription to unsubscribe from.
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
        example: b30faba9-982a-4d14-8af1-7ec85454b6b7
      responses:
        '403':
          description: You do not have access to this session.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: The session ID could not be found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '204':
          description: The subscription has been removed.
      deprecated: true
  /v1/eventSources/{sourceId}/subscriptions/{subscriptionId}:
    delete:
      tags:
      - channel-service
      summary: Unsubscribe from events
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Cancel an existing subscription. After this operation, the event stream
        will no longer contain events for this subscription. <br/> Scope: []"
      operationId: unsubscribe
      parameters:
      - name: btxSession
        in: cookie
        description: The session affinity cookie. Pass the cookie value returned by
          previous API calls.
        required: false
        schema:
          type: string
      - name: sourceId
        in: path
        description: "The ID of an event source that has already been created.\nThe
          requested subscriptions will be appended to this event source.\n"
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
      - name: subscriptionId
        in: path
        description: The ID of the subscription to unsubscribe from.
        required: true
        schema:
          maxLength: 256
          minLength: 0
          type: string
        example: b30faba9-982a-4d14-8af1-7ec85454b6b7
      responses:
        '404':
          description: The event source ID could not be found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: You do not have access to this event source.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '204':
          description: The subscription has been removed.
components:
  schemas:
    CategoryFilter:
      required:
      - test
      - type
      type: object
      description: "A Message Filter that, when applied, will only allow for messages
        to be received by the message channel for whom the message category matches
        at least one of the categories listed in the 'test' property.\n"
      example:
        type: CATEGORY
        test:
        - specific-category
        - another-specific-category
      allOf:
      - $ref: '#/components/schemas/MessageFilter'
      - type: object
        properties:
          test:
            maxLength: 256
            minLength: 1
            maxItems: 256
            minItems: 1
            type: array
            description: The list of categories that must be filtered.
            example:
            - specific-category
            - another-specific-category
            items:
              maxLength: 256
              minLength: 1
              type: string
              description: The list of categories that must be filtered.
              example: '["specific-category","another-specific-category"]'
    ChannelFilter:
      required:
      - test
      - type
      type: object
      description: "A Message Filter that, when applied, will only allow for messages
        to be received by the message channel for whom the name of the channel starts
        with the list of channel name prefixes listed in the 'test' property.\n"
      example:
        type: CHANNEL
        test:
        - specific-channel
        - another-specific-channel
      allOf:
      - $ref: '#/components/schemas/MessageFilter'
      - type: object
        properties:
          test:
            maxLength: 256
            minLength: 1
            maxItems: 256
            minItems: 1
            type: array
            description: The list of channel name prefixes that must be filtered.
            example:
            - specific-channel
            - another-specific-channel
            items:
              maxLength: 256
              minLength: 1
              type: string
              description: The list of channel name prefixes that must be filtered.
              example: '["specific-channel","another-specific-channel"]'
    MessageFilter:
      required:
      - type
      type: object
      properties:
        type:
          type: string
          description: The type of this Message Filter.
          enum:
          - CATEGORY
          - TYPE
          - CHANNEL
          - TYPE
          - CATEGORY
          - CHANNEL
      description: "The Message Filters that determine if a message must be delivered
        for the new subscription.\nAll Message Filters of a single subscription are
        combined with boolean AND-logic.\nEvent sources will deliver messages of all
        subscriptions.\nIn other words, multiple subscriptions are combined with boolean
        OR-logic.\nIn typical use cases, a subscription will filter on a message category,
        then maybe type and/or channel.\n"
      discriminator:
        propertyName: type
        mapping:
          TYPE: '#/components/schemas/TypeFilter'
          CATEGORY: '#/components/schemas/CategoryFilter'
          CHANNEL: '#/components/schemas/ChannelFilter'
    SubscribeRequest:
      type: object
      properties:
        subscriptions:
          maxItems: 128
          minItems: 0
          type: array
          description: List of subscriptions to subscribe to.
          items:
            $ref: '#/components/schemas/Subscription'
      description: "Immediately subscribe to message events.\nOptional.\nTypically
        users will subscribe to a category and a channel, maybe with additional filters
        narrowing down the messages received even more.\nOther filters usually follow
        after the channel filter.\n"
      example:
        subscriptions:
        - filters:
          - type: CATEGORY
            test:
            - myCategory
          - type: CHANNEL
            test:
            - d6a10e10-17c9-4081-9f54-8a218f00eba8/bb23bbff-7326-462f-80bc-4a3c5d66567e
    Subscription:
      type: object
      properties:
        filters:
          maxItems: 1024
          minItems: 0
          type: array
          description: "The Message Filters that determine if a message must be delivered
            for the new subscription.\nAll Message Filters of a single subscription
            are combined with boolean AND-logic.\nEvent sources will deliver messages
            of all subscriptions.\nIn other words, multiple subscriptions are combined
            with boolean OR-logic.\nIn typical use cases, a subscription will filter
            on a message category, then maybe type and/or channel.\n"
          items:
            oneOf:
            - $ref: '#/components/schemas/MessageFilter'
            - $ref: '#/components/schemas/CategoryFilter'
            - $ref: '#/components/schemas/ChannelFilter'
            - $ref: '#/components/schemas/TypeFilter'
      description: List of subscriptions to subscribe to.
      example:
        filters:
        - type: CATEGORY
          test:
          - myCategory
        - type: TYPE
          test:
          - myType
        - type: CHANNEL
          test:
          - myChannel
    TypeFilter:
      required:
      - test
      - type
      type: object
      description: "A Message Filter that, when applied, will only allow for messages
        to be received by the message channel for whom the message type matches at
        least one of the types listed in the 'test' property.\n"
      example:
        type: TYPE
        test:
        - specific-type
        - another-specific-type
      allOf:
      - $ref: '#/components/schemas/MessageFilter'
      - type: object
        properties:
          test:
            maxLength: 256
            minLength: 1
            maxItems: 256
            minItems: 1
            type: array
            description: The subject that must be filtered, typically the subjectId
              whose permissions will be checked.
            example:
            - specific-type
            - another-specific-type
            items:
              maxLength: 256
              minLength: 1
              type: string
              description: The subject that must be filtered, typically the subjectId
                whose permissions will be checked.
              example: '["specific-type","another-specific-type"]'
    SubscribeResponse:
      required:
      - subscriptionIds
      type: object
      properties:
        subscriptionIds:
          type: array
          description: List of created subscriptions.
          items:
            type: string
      description: "Subscriptions have been made successfully.\nThe returned values
        are the IDs of the new subscriptions.\nAfter a subscription was successfully
        made, clients of the [**receive-events-endpoint**](../../../docs/foundation/channel/receive-events)
        will immediately start to receive events for those subscriptions.\n"
      example:
        subscriptionIds:
        - b30faba9-982a-4d14-8af1-7ec85454b6b7
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
          format: uri
        properties:
          type: object
          additionalProperties:
            type: object
    SessionResponse:
      required:
      - sessionId
      type: object
      properties:
        sessionId:
          type: string
          description: "The ID of the created session.\nUse this ID to subscribe/unsubscribe
            to messages and to get the event stream.\n"
        subscriptionIds:
          type: array
          description: "The IDs of the requested subscriptions.\nIf no subscriptions
            were requested to be created, this will not be set.\n"
          example: b30faba9-982a-4d14-8af1-7ec85454b6b7
          items:
            type: string
      description: "Response indicating a new session was created.\nThe subscriptions
        that were requested, were also automatically created and their IDs are returned.\n
        If no subscriptions were requested to be created, subscriptionIds will not
        be set.\nTheir IDs are returned as well.\nTo start receiving events, refer
        to [**the receive events API**](../../../docs/foundation/channel/receive-events).\n"
      example:
        sessionId: e298b340-ca8c-4737-98c6-3e73bb1baf7f
        subscriptionIds:
        - b30faba9-982a-4d14-8af1-7ec85454b6b7
    MessageEventSourceRequest:
      type: object
      properties:
        subscriptions:
          maxItems: 128
          minItems: 0
          type: array
          description: Subscriptions to immediately create and activate upon request
            completion.
          items:
            $ref: '#/components/schemas/Subscription'
      description: "Immediately subscribe to message events.\nOptional.\nTypically
        users will subscribe to a category first, and then to a channel.\nOther filters
        usually follow after the channelfilter.\n"
      example:
        subscriptions:
        - filters:
          - type: CATEGORY
            test:
            - myCategory
          - type: CHANNEL
            test:
            - d6a10e10-17c9-4081-9f54-8a218f00eba8/bb23bbff-7326-462f-80bc-4a3c5d66567e
    MessageEventSourceResponse:
      required:
      - eventSourceId
      type: object
      properties:
        eventSourceId:
          type: string
          description: "The ID of the created eventSource.\nUse this ID to subscribe/unsubscribe
            to messages and to get the event stream.\n"
        subscriptionIds:
          type: array
          description: "The IDs of the requested subscriptions.\nIf no subscriptions
            were requested to be created, this will not be set.\n"
          example: b30faba9-982a-4d14-8af1-7ec85454b6b7
          items:
            type: string
      description: "Response indicating a new eventSource was created.\nThe subscriptions
        that were requested, were also automatically created and their IDs are returned.\n
        If no subscriptions were requested to be created, subscriptionIds will not
        be set.\nTheir IDs are returned as well.\nTo start receiving events, refer
        to [**the receive events API**](../../../docs/foundation/channel/receive-events).\n"
      example:
        eventSourceId: e298b340-ca8c-4737-98c6-3e73bb1baf7f
        subscriptionIds:
        - b30faba9-982a-4d14-8af1-7ec85454b6b7
    ServerSentEventEvent:
      type: object
  securitySchemes:
    channel:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/v1/oauth20/authorization
          tokenUrl: https://api.uat.btx.fr.banqup.com/v1/oauth20/token_kc
          scopes: {}
