openapi: 3.0.1
info:
  title: Plugin Service API
  version: 1.0.0
servers:
- description: The Plugin API REST endpoint
  url: https://api.cve.btx.eu.banqup.com/core/plugin
paths:
  /v2/pluginInterfaces/{pluginInterfaceId}:
    get:
      tags:
      - plugin-interface
      summary: Get plugin interface
      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/> Gets details about a plugin interface. <br/> Scope: []<br/> This Endpoint
        is part of: plugin-service"
      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'
  /v2/pluginInterfaces/{pluginInterfaceId}/plugins:
    get:
      tags:
      - plugin
      summary: List plugins
      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/> Lists all plugins of a given plugin interface that the caller has access
        to. <br/> Scope: []<br/> This Endpoint is part of: plugin-service"
      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: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Registers a plugin of an existing plugin interface. The creator of a
        plugin also receives permissions to manage that plugin. <br/> Scope: []<br/>
        This Endpoint is part of: plugin-service"
      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: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Lists all plugin interfaces. <br/> Scope: []<br/> This Endpoint is part
        of: plugin-service"
      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'
  /v2/pluginInterfaces/{pluginInterfaceId}/plugins/{pluginId}:
    get:
      tags:
      - plugin
      summary: Get plugin
      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/> Gets information about a registered plugin of a plugin interface. <br/>
        Scope: []<br/> This Endpoint is part of: plugin-service"
      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: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Unregisters a plugin. <br/> Scope: []<br/> This Endpoint is part of:
        plugin-service"
      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
      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.cve.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.cve.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
