openapi: 3.0.0
info:
  description: This is the Schema Catalog API
  version: "1.0.0"
  title: Schema API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: admins
    description: Secured Admin-only calls
  - name: developers
    description: Operations available to regular developers
paths:
  /schema:
    get:
      tags:
        - developers
      summary: schema list of loaded catalogs
      operationId: searchCatalog
      description: |
        By passing in the appropriate search attributes, you can search for
        available catalogs in the system
      parameters:
        - in: query
          name: searchString
          description: pass an optional search string for looking up catalog components
          required: false
          schema:
            type: string
        - in: query
          name: limit
          description: maximum number of records to return
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 50
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
              example:
                observability:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
                    examples:
                      catalog: observability
                      version: '1.0'
                      url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability
                      categories:
                        - category: logs
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs
                          components:
                            - component: log
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/logs
                              container: true
                              tags: [ ]
                            - component: http
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/http
                              tags: [ ]
                              container: false
                            - component: communication
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/communication
                              tags:
                                - web
                              container: false
                        - category: traces
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces
                          components:
                            - component: span
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces
                              tags: [ ]
                              container: true
                        - category: metrics
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics
                          components:
                            - component: metric
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics/metrics
                              tags: [ ]
                              container: true
        '400':
          description: bad input parameter
    post:
      tags:
        - admins
      summary: adds a catalog item
      operationId: addCatalog
      description: |
        Adds a catalog item to the system, expecting the internal URLs to be accessible
      requestBody:
        description: Inventory item to add
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
            example:
              observability:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
                  examples:
                    catalog: observability
                    version: '1.0'
                    url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability
                    categories:
                      - category: logs
                        version: '1.0'
                        url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs
                        components:
                          - component: log
                            version: '1.0'
                            url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/logs
                            container: true
                            tags: [ ]
                          - component: http
                            version: '1.0'
                            url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/http
                            tags: [ ]
                            container: false
                          - component: communication
                            version: '1.0'
                            url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/communication
                            tags:
                              - web
                            container: false
                      - category: traces
                        version: '1.0'
                        url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces
                        components:
                          - component: span
                            version: '1.0'
                            url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces/traces
                            tags: [ ]
                            container: true
                      - category: metrics
                        version: '1.0'
                        url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics
                        components:
                          - component: metric
                            version: '1.0'
                            url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics/metrics
                            tags: [ ]
                            container: true

      responses:
        '201':
          description: item created
        '400':
          description: 'invalid input, object invalid'
        '409':
          description: an existing item already exists
  /schema/{id}:
    get:
      tags:
        - developers
      summary: get catalog by id
      operationId: catalogById
      description: |
        Get a specific catalog by Id
      parameters:
        - in: path
          name: id
          description: catalog schema Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: catalog
          content:
            application/json:
              schema:
                $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
              example:
                observability:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/catalog.schema'
                    examples:
                      catalog: observability
                      version: '1.0'
                      url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability
                      categories:
                        - category: logs
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs
                          components:
                            - component: log
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/logs
                              container: true
                              tags: [ ]
                            - component: http
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/http
                              tags: [ ]
                              container: false
                            - component: communication
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/logs/communication
                              tags:
                                - web
                              container: false
                        - category: traces
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces
                          components:
                            - component: span
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/traces/traces
                              tags: [ ]
                              container: true
                        - category: metrics
                          version: '1.0'
                          url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics
                          components:
                            - component: metric
                              version: '1.0'
                              url: https://github.com/opensearch-project/opensearch-catalog/tree/main/schema/observability/metrics/metrics
                              tags: [ ]
                              container: true
        '400':
          description: bad input parameter
  /schema/{id}/dictionary:
    get:
      tags:
        - developers
      summary: get catalog's dictionary according to it's id
      operationId: catalogDictionaryById
      description: |
        Get a specific catalog dictionary by it's Id
      parameters:
        - in: path
          name: id
          description: catalog instance Id
          required: true
          schema:
            type: string
        - in: query
          name: query
          description: filter by query on any of (category, component, name)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: catalog dictionary
          content:
            application/json:
              schema:
                $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/dictionary.schema'
              example:
                observability:
                  application/json:
                    schema:
  /schema/{id}/instances:
    get:
      tags:
        - developers
      summary: get catalog's instances according to it's id
      operationId: catalogInstancesById
      description: |
        Get a specific catalog Instances by it's Id
      parameters:
        - in: path
          name: id
          description: catalog schema Id
          required: true
          schema:
            type: string
        - in: query
          name: query
          description: filter by query on any of (category,component,name)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: catalog instances
          content:
            application/json:
              schema:
                $ref: 'https://github.com/opensearch-project/opensearch-catalog/blob/main/schema/system/instances.schema'
              example:
                observability:
                  application/json:
                    schema:

servers:
  - url: http://127.0.0.1:4010
    description: Mock server (uses fake data)