openapi: 3.0.3
info:
  title: Extension Template Management Rest API Definition
  description: This document specifies an the extension resource management service RESTful API
  version: 1.0.11
externalDocs:
  description: Find out more about extension management service
  url: http://swagger.io
servers:
  - url: 'https://{server-url}/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: "carbon.super"
      server-url:
        default: "localhost:9443"
tags:
  - name: Browse
    description: Browse the extensions

paths:
  '/extensions':
    get:
      tags:
        - Browse
      summary: List the extensions.
      description: |
        This API provides the capability to retrieve the extensions
        that are registered in the system.<br>
          <b>Permission required:</b> <br>
              * TBD <br>
          <b>Scope required:</b> <br>
              * TBD
      operationId: listExtensions
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtensionListItem'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/extensions/{extensionType}':
    get:
      tags:
        - Browse
      summary: List the extensions by type.
      description: |
        This API provides the capability to retrieve the extensions
        that are registered in the system.<br>
          <b>Permission required:</b> <br>
              * TBD <br>
          <b>Scope required:</b> <br>
              * TBD
      operationId: listExtensionsByType
      parameters:
        - name: extensionType
          in: path
          description: ID of the extension
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtensionListItem'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/extensions/{extensionType}/{extensionId}':
    get:
      tags:
        - Browse
      summary: Get the extension info by type and id.
      operationId: getExtensionInfoById
      description: |
        This API provides the capability to retrieve the extension
        that is registered in the system.<br>
          <b>Permission required:</b> <br>
              * TBD <br>
          <b>Scope required:</b> <br>
              * TBD
      parameters:
        - name: extensionType
          in: path
          description: Type of the extension
          required: true
          schema:
            type: string
        - name: extensionId
          in: path
          description: ID of the extension.
          required: true
          schema:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionResponseModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/extensions/{extensionType}/{extensionId}/metadata':
    get:
      tags:
        - Browse
      summary: Get the extension metadata by type and id.
      operationId: getMetadataById
      description: |
        This API provides the capability to retrieve the extension metadata
        that is registered in the system.<br>
          <b>Permission required:</b> <br>
              * TBD <br>
          <b>Scope required:</b> <br>
              * TBD
      parameters:
        - name: extensionType
          in: path
          description: Type of the extension
          required: true
          schema:
            type: string
        - name: extensionId
          in: path
          description: ID of the extension.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetadataResponseModel'
              examples:
                extensions:
                  $ref: '#/components/examples/MetadataResponseModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/extensions/{extensionType}/{extensionId}/template':
    get:
      tags:
        - Browse
      summary: Get the extension template by type and id.
      operationId: getTemplateById
      description: |
        This API provides the capability to retrieve the extension template
        that is registered in the system.<br>
          <b>Permission required:</b> <br>
              * TBD <br>
          <b>Scope required:</b> <br>
              * TBD
      parameters:
        - name: extensionType
          in: path
          description: Type of the extension
          required: true
          schema:
            type: string
        - name: extensionId
          in: path
          description: ID of the extension.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseModel'
              examples:
                extensions:
                  $ref: '#/components/examples/TemplateResponseModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


components:
  schemas:
    ExtensionResponseModel:
      type: object
      properties:
        id:
          type: string
          example: 'd7c8549f-32af-4f53-9013-f66f1a6c67bf'
        version:
          type: string
          description: The version of the current extension resource.
          example: 'v1.0.0'
        name:
          type: string
          example: 'google-oidc'
        displayName:
          type: string
          example: 'Google Auth'
        description:
          type: string
          example: 'Google Auth Connection'
        image:
          type: string
          example: 'google-oidc.png'
        displayOrder:
          type: integer
          format: int32
          example: 3
        tags:
          type: array
          items:
              type: string
              example: 'OIDC'
        category:
          type: string
          example: 'DEFAULT'
        type:
          type: string
          example: 'connection'

    ExtensionListItem:
      type: object
      properties:
        id:
          type: string
          example: 'd7c8549f-32af-4f53-9013-f66f1a6c67bf'
        version:
          type: string
          description: The version of the current extension resource.
          example: 'v1.0.0'
        name:
          type: string
          example: 'google-oidc'
        description:
          type: string
          example: 'Google Auth Connection'
        image:
          type: string
          example: 'google-oidc.png'
        displayOrder:
          type: integer
          format: int32
          example: 3
        tags:
          type: array
          items:
            type: string
            example: 'OIDC'
        customAttributes:
          type: array
          items:
            type: object
            additionalProperties: { }
        category:
          type: string
          example: 'DEFAULT'
        type:
          type: string
          example: 'connection'
        self:
          type: string
          example: 'https://localhost:9443/api/v1/extensions/connection/d7c8549f-32af-4f53-9013-f66f1a6c67bf'

    TemplateResponseModel:
      type: object

    MetadataResponseModel:
      type: object

    Error:
      type: object
      properties:
        code:
          type: string
          example: EXT-00000
        message:
          type: string
          example: Some error message.
        description:
          type: string
          example: Some error description.
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047
  examples:
    MetadataResponseModel:
      value:
        - name: "name"
          type: "string"
          displayName: "Name"
          required: true
          location: "$name"
        - name: "description"
          type: "string"
          displayName: "Description"
          required: false
          location: "$description"
    TemplateResponseModel:
      value:
        name: "google-oidc"
        description: "Google Auth Connection"
        image: "google-oidc.png"
        isPrimary: true
        isFederationHub: false
        homeRealmIdentifier: ""
        certificates:
          certificates: []
        alias: "google-oidc"
        claims: []
        roles: []
        federatedAuthenticators: {
          defaultAuthenticatorId: "google-oidc",
            authenticators: [
              {
                name: "google-oidc",
                displayName: "Google",
                enabled: true,
                isDefault: true,
                properties: [
                  {
                    name: "ClientId",
                    value: "xxxxxxxxxxxxxxxxx"
                  }
                ]
              }
            ]
        }
