openapi: 3.0.1
info:
  title: Plugin Service API
  version: 1.0.0
servers:
- description: The Plugin API REST endpoint
  url: https://api.uat.btx.eu.banqup.com/core/plugin
- description: The Plugin API REST endpoint
  url: https://api.uat.btx.fr.banqup.com/core/plugin
paths:
  /v2/pluginInterfaces/{pluginInterfaceId}:
    get:
      tags:
      - plugin-interface
      summary: Get plugin interface
      description: Gets details about a plugin interface.
      operationId: getPluginInterface
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Retrieved the plugin interface.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
    put:
      tags:
      - plugin-interface
      summary: Replace plugin interface
      description: Fully replaces the existing plugin interface with new configuration.
      operationId: replacePluginInterface
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginInterfaceRequest'
        required: true
      responses:
        '200':
          description: Updated/replaced the plugin interface.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '403':
          description: You must have the permission ‘plugin_interface_manage’ on the
            plugin interface that is in your request. The creator of the plugin interface
            receives this permission automatically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
    delete:
      tags:
      - plugin-interface
      summary: Delete a plugin interface
      description: Removes an existing plugin interface. This will also delete all
        registered plugins.
      operationId: deletePluginInterface
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted the plugin interface.
        '403':
          description: You must have the permission 'plugin_interface_manage' on the
            plugin interface that is in your request. The creator of the plugin interface
            receives this permission automatically.
    patch:
      tags:
      - plugin-interface
      summary: Update plugin interface
      description: Applies the given JSON patch to the configuration of an existing
        plugin interface. The patch operation is applied to the data structure the
        client would receive on a Get plugin interface operation.
      operationId: updatePluginInterface
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
        required: true
      responses:
        '200':
          description: Updated/patched the plugin interface field(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '403':
          description: You must have the permission 'plugin_interface_manage' on the
            plugin interface that is in your request. The creator of the plugin interface
            receives this permission automatically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
  /api/v1/extensionPoints/{extensionPointId}:
    put:
      tags:
      - extension-point
      summary: ⚠️Replace extension point
      description: Fully replaces the existing extension point with new configuration.
      operationId: replaceExtensionPoint
      parameters:
      - name: extensionPointId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtensionPointRequest'
        required: true
      responses:
        '200':
          description: Updated/replaced the extension point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '403':
          description: You must have the permission ‘extension_point_manage’ on the
            extension point that is in your request. The creator of the extension
            point receives this permission automatically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      deprecated: true
    delete:
      tags:
      - extension-point
      summary: Delete an extension point
      description: Removes an existing extension point. This will also delete all
        registered extensions.
      operationId: deleteExtensionPoint
      parameters:
      - name: extensionPointId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted the extension point.
        '403':
          description: You must have the permission 'extension_point_manage' on the
            extension point that is in your request. The creator of the extension
            point receives this permission automatically.
      deprecated: true
    patch:
      tags:
      - extension-point
      summary: Update extension point
      description: Applies the given JSON patch to the configuration of an existing
        extension point. The patch operation is applied to the data structure the
        client would receive on a Get extension point operation.
      operationId: updateExtensionPoint
      parameters:
      - name: extensionPointId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
        required: true
      responses:
        '200':
          description: Updated/patched the extension point field(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '403':
          description: You must have the permission 'extension_point_manage' on the
            extension point that is in your request. The creator of the extension
            point receives this permission automatically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      deprecated: true
  /v2/pluginInterfaces/{pluginInterfaceId}:reAuthorize:
    post:
      tags:
      - plugin-interface
      summary: Reauthorize all plugins
      description: Re-run this plugin interface's authorizer on each plugin. This
        may result in one or more plugins being deleted if the authorizer disallows
        them.
      operationId: reAuthorizePlugins
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Reauthorized all plugins.
        '403':
          description: You must have the permission 'plugin_interface_manage' on the
            plugin interface that is in your request. The creator of the plugin interface
            receives this permission automatically.
  /v2/pluginInterfaces/{pluginInterfaceId}/plugins:
    get:
      tags:
      - plugin
      summary: List plugins
      description: Lists all plugins of a given plugin interface that the caller has
        access to.
      operationId: listPlugins
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Listed plugins.
          content:
            application/x-ndjson:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plugin'
            application/json:
              schema:
                $ref: '#/components/schemas/PluginList'
    post:
      tags:
      - plugin
      summary: Register a plugin
      description: Registers a plugin of an existing plugin interface. The creator
        of a plugin also receives permissions to manage that plugin.
      operationId: registerPlugin
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginRequest'
        required: true
      responses:
        '201':
          description: Registered the plugin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
  /v2/pluginInterfaces:
    get:
      tags:
      - plugin-interface
      summary: List plugin interfaces
      description: Lists all plugin interfaces.
      operationId: listPluginInterfaces
      parameters:
      - name: namespace
        in: query
        required: false
        schema:
          type: string
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: version
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Listed plugin interfaces.
          content:
            application/x-ndjson:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PluginInterface'
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterfaceList'
    post:
      tags:
      - plugin-interface
      summary: Create a new plugin interface
      description: Creates a new plugin interface and grants the creator permission
        to manage that plugin interface.
      operationId: createPluginInterface
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginInterfaceRequest'
        required: true
      responses:
        '201':
          description: Created the plugin interface.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '403':
          description: You must have the permission 'plugin_interface_create' on the
            plugin interface that is in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInterface'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
  /api/v1/extensionPoints/{extensionPointId}:reAuthorize:
    post:
      tags:
      - extension-point
      summary: ⚠️ Reauthorize all extensions
      description: Re-run this extension point's authorizer on each extension. This
        may result in one or more extensions being deleted if the authorizer disallows
        them.
      operationId: reAuthorizeExtensions
      parameters:
      - name: extensionPointId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Reauthorized all extensions.
        '403':
          description: You must have the permission 'extension_point_manage' on the
            extension point that is in your request. The creator of the extension
            point receives this permission automatically.
      deprecated: true
  /api/v1/extensionPoints:
    post:
      tags:
      - extension-point
      summary: ⚠️Create a new extension point
      description: Creates a new extension point and grants the creator permission
        to manage that extension point.
      operationId: createExtensionPoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtensionPointRequest'
        required: true
      responses:
        '201':
          description: Created the extension point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '403':
          description: You must have the permission 'extension_point_create' on the
            extension point that is in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionPointResponse'
        '409':
          description: Already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      deprecated: true
  /v2/pluginInterfaces/{pluginInterfaceId}/plugins/{pluginId}:
    get:
      tags:
      - plugin
      summary: Get plugin
      description: Gets information about a registered plugin of a plugin interface.
      operationId: getPlugin
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: pluginId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Retrieved the plugin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
    delete:
      tags:
      - plugin
      summary: Delete plugin
      description: Unregisters a plugin.
      operationId: deletePlugin
      parameters:
      - name: pluginInterfaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: pluginId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Cache-Control
        in: header
        required: false
        schema:
          type: string
      responses:
        '204':
          description: Deleted the plugin.
components:
  schemas:
    AuthorizationEndpoint:
      required:
      - url
      type: object
      properties:
        url:
          minLength: 1
          type: string
          description: The callback url that will be called during authorization of
            new Plugin registrations.
          example: http://example.com/my-plugin-authorizer
        authorizationHeader:
          type: string
          description: An optional header that will be sent as an Authorization header
            when the Plugin Service Authorization Endpoint is being called. The implementer
            of the authorization endpoint can use this value to validate the authenticity
            of incoming requests. We recommend a strong secret.
        httpSignature:
          type: boolean
    PluginInterfaceRequest:
      required:
      - name
      - namespace
      - version
      type: object
      properties:
        namespace:
          minLength: 1
          type: string
          description: The namespace for which the Plugin Interface should be created.
          example: my-namespace
        name:
          minLength: 1
          type: string
          description: The name of the Plugin Interface to be created.
          example: my-plugin-interface
        version:
          type: string
          description: The version of the Plugin Interface to be created.
          example: '1.0'
        public:
          type: boolean
          description: |
            Describes if the Plugin Interface should be public.
            A public Plugin Interface's Plugins can be listed by everyone.
            If non public you need additional permissions when listing Plugins of this Plugin Interface.
            These additional permissions are automatically granted to the user that registered the Plugin Interface.
          example: true
          default: false
        authorizationEndpoint:
          $ref: '#/components/schemas/AuthorizationEndpoint'
    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
    PluginInterface:
      required:
      - name
      - namespace
      - pluginInterfaceId
      - public
      type: object
      properties:
        pluginInterfaceId:
          type: string
          description: The identifier of the Plugin Interface.
          format: uuid
          example: 41b86461-2c30-4cc6-8892-ea342d2e546b
        namespace:
          minLength: 1
          type: string
          description: The namespace of the Plugin Interface.
          example: my.namespace
        name:
          minLength: 1
          type: string
          description: The name of the Plugin Interface.
          example: my-plugin-interface
        version:
          type: string
          description: The version of the Plugin Interface.
          example: '1.0'
        public:
          type: boolean
          description: |
            Describes if the Plugin Interface should be public.
            A public Plugin Interface's Plugins can be listed by everyone.
            If non public you need additional permissions when listing Plugins of this Plugin Interface.
            These additional permissions are automatically granted to the user that registered the Plugin Interface.
          example: true
        authorizationEndpoint:
          $ref: '#/components/schemas/AuthorizationEndpoint'
    ExtensionPointRequest:
      required:
      - name
      - namespace
      - version
      type: object
      properties:
        namespace:
          minLength: 1
          type: string
        name:
          minLength: 1
          type: string
        version:
          type: string
        public:
          type: boolean
          default: false
        authorizationEndpoint:
          $ref: '#/components/schemas/AuthorizationEndpoint'
    ExtensionPointResponse:
      required:
      - extensionPointId
      - name
      - namespace
      - public
      type: object
      properties:
        extensionPointId:
          type: string
          format: uuid
        namespace:
          minLength: 1
          type: string
        name:
          minLength: 1
          type: string
        version:
          type: string
        public:
          type: boolean
        authorizationEndpoint:
          $ref: '#/components/schemas/AuthorizationEndpoint'
    JsonNode:
      type: object
      description: The data needed for plugin registration. The format of this required
        data is dictated by the Plugin Interface for which you are registering a Plugin.
    PluginRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/JsonNode'
    Plugin:
      required:
      - pluginId
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the Plugin.
          format: uuid
          example: 41b86461-2c30-4cc6-8892-ea342d2e546b
        authorizationInfo:
          $ref: '#/components/schemas/JsonNode'
        data:
          $ref: '#/components/schemas/JsonNode'
        created:
          type: string
          description: The time when the Plugin was registered.
          format: date-time
    ExtensionRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/JsonNode'
    ExtensionResponse:
      required:
      - extensionId
      type: object
      properties:
        extensionId:
          type: string
          format: uuid
        authorizationInfo:
          $ref: '#/components/schemas/JsonNode'
        data:
          $ref: '#/components/schemas/JsonNode'
        created:
          type: string
          format: date-time
    JsonPatch:
      type: object
    PluginList:
      type: object
      properties:
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/Plugin'
    PluginInterfaceList:
      type: object
      properties:
        pluginInterfaces:
          type: array
          items:
            $ref: '#/components/schemas/PluginInterface'
    ExtensionResponseList:
      type: object
      properties:
        extensions:
          type: array
          items:
            $ref: '#/components/schemas/ExtensionResponse'
    ExtensionPointResponseList:
      type: object
      properties:
        extensionPoints:
          type: array
          items:
            $ref: '#/components/schemas/ExtensionPointResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.uat.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.uat.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.uat.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
