aihub-dag/elyra/api/elyra.yaml

#
# Copyright 2018-2022 Elyra Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
openapi: 3.0.1
info:
  title: Elyra API
  description: The API for the Elyra extensions.
  contact:
    name: Elyra
    url: https://github.com/elyra-ai/elyra
  version: "1"

paths:

  /elyra/elyra.yaml:
    get:
      tags:
        - api
      summary: Get API information (yaml).
      responses:
        200:
          description: Returns a swagger specification in yaml.
          content:
            text/x-yaml:
              schema:
                type: string
        500:
          description: Unexpected error.

  /elyra/schemaspace:
    get:
      tags:
        - schemaspace
      summary: Get current schemaspace names.
      responses:
        200:
          description: Returns the list of current schemaspace names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemaspaces:
                    items: {
                      type: string
                    }
                    description: The list of current schemaspace names.
        500:
          description: Unexpected error.

  /elyra/schemaspace/{schemaspace_name_or_id}:
    get:
      tags:
        - schemaspace
      summary: Get properties for a given schemaspace.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Returns the single-valued properties of the current schemaspace.
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/SchemaspaceResource'
        404:
          description: Schemaspace not found.
          content: {}
        500:
          description: Unexpected error.

  /elyra/schema/{schemaspace_name_or_id}:
    get:
      tags:
        - schema
      summary: Get schemas for a given schemaspace
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace
          required: true
          schema:
            type: string
      responses:
        200:
          description: Returns the schema instances for a given schemaspace name or id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemaspace:
                    type: array
                    description: The schema instances within the schemaspace.
                    items:
                      $ref: '#/components/schemas/SchemaResource'
        404:
          description: Schemaspace not found.
          content: {}
        500:
          description: Unexpected error.

  /elyra/schema/{schemaspace_name_or_id}/{resource}:
    get:
      tags:
        - schema
      summary: Get a given schema instance from a given schemaspace name or id.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
        - name: resource
          in: path
          description: The name of the resource in a given schemaspace.
          required: true
          schema:
            type: string
      responses:
        200:
          description: The named schema instance within the schemaspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResource'
        404:
          description: Schemaspace/Resource not found.
          content: {}
        500:
          description: Unexpected error.

  /elyra/metadata/{schemaspace_name_or_id}:
    get:
      tags:
        - metadata
      summary: Get metadata for a given schemaspace name or id.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
      responses:
        200:
          description: The metadata instances within the schemaspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemaspace:
                    type: array
                    description: The name of the schemaspace.
                    items:
                      $ref: '#/components/schemas/MetadataResource'
        400:
          description: An error (validation, syntax) occurred relative to the instance data.
        404:
          description: Schemaspace not found.
          content: {}
        500:
          description: Unexpected error.
    post:
      tags:
        - metadata
      summary: Create a metadata instance in a given schemaspace.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataResourceBody'

      responses:
        201:
          description: The newly-created metadata instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResource'
          headers:
            Location:
              description: Resource endpoint
              schema:
                type: string
                format: url
        400:
          description: An error (validation, syntax) occurred relative to the instance data.
        404:
          description: Schemaspace not found.
        409:
          description: Resource already exists.
        500:
          description: Unexpected error.

  /elyra/metadata/{schemaspace_name_or_id}/{resource}:
    get:
      tags:
        - metadata
      summary: Get a given metadata instance from a given schemaspace name or id.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
        - name: resource
          in: path
          description: The name of the resource in a given schemaspace.
          required: true
          schema:
            type: string
      responses:
        200:
          description: The named metadata instance within the schemaspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResource'
        400:
          description: An error (validation, syntax) occurred relative to the instance data.
        404:
          description: Schemaspace/Resource not found.
          content: {}
        500:
          description: Unexpected error.

    put:
      tags:
        - metadata
      summary: Update a given metadata resource within a given schemaspace.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
        - name: resource
          in: path
          description: The name of the resource in a given schemaspace.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataResourceBody'

      responses:
        200:
          description: The updated metadata instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResource'
        400:
          description: An error (validation, syntax, not supported) occurred relative to the instance data.
        404:
          description: The resource to update was not found.
        500:
          description: Unexpected error.

    delete:
      tags:
        - metadata
      summary: Delete a given metadata resource from a given schemaspace.
      parameters:
        - name: schemaspace_name_or_id
          in: path
          description: The name or id of the schemaspace.
          required: true
          schema:
            type: string
        - name: resource
          in: path
          description: The name of the resource in a given schemaspace.
          required: true
          schema:
            type: string
      responses:
        204:
          description: The resource was successfully deleted.
        400:
          description: An error (validation, syntax) occurred relative to the instance data.
        403:
          description: Deletion of the resource is not permitted.
        404:
          description: The resource was not found.
        500:
          description: Unexpected error.

  /elyra/pipeline/components/cache:
    put:
      tags:
        - component
      summary: Initiates a refresh of the entire component cache.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComponentCacheResource'
      responses:
        204:
          description: The refresh request was initiated successfully.
        400:
          description: Invalid request, malformed body.
        409:
          description: Cache refresh is in progress - try request later.

  /elyra/pipeline/components/cache/{catalog}:
    parameters:
      - name: catalog
        in: path
        description: The name of the component catalog to refresh
        required: true
        schema:
          type: string
    put:
      tags:
        - component
      summary: Initiates a refresh of the given component catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComponentCacheResource'
      responses:
        204:
          description: The refresh request was initiated successfully.
        400:
          description: Invalid request, malformed body.
        404:
          description: Catalog not found.

  /elyra/pipeline/components/{processor}:
    parameters:
      - name: processor
        in: path
        description: The name of the runtime processor.  Will match the runtime schema name (e.g., "kfp", "airflow", etc.).
        required: true
        schema:
          type: string
    get:
      tags:
        - pipeline
        - component
      summary: Fetch all components associated with the given runtime processor.
      responses:
        200:
          description: The components relative to the given runtime processor for use in the Elyra front-end.
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid runtime processor.

  /elyra/pipeline/components/{processor}/{component_id}/properties:
    parameters:
      - name: processor
        in: path
        description: The name of the runtime processor.  Will match the runtime schema name (e.g., "kfp", "airflow", etc.).
        required: true
        schema:
          type: string
      - name: component_id
        in: path
        description: The component identifier - composed of the catalog connector schema name, ":", and the component's hash.
        required: true
        schema:
          type: string
    get:
      tags:
        - pipeline
        - component
      summary: Fetch a component's properties for use in the Elyra front-end
      responses:
        200:
          description: JSON containing the component definition.
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid runtime processor or component ID.

 /elyra/pipeline/{processor}/properties:
    parameters:
      - name: processor
        in: path
        description: The name of the runtime processor.  Will match the RuntimeType string form (e.g., "KUBEFLOW_PIPELINES", "AIRFLOW", etc.).
        required: true
        schema:
          type: string
    get:
      tags:
        - pipeline
      summary: Fetch a pipeline's properties for use in the Elyra front-end
      responses:
        200:
          description: JSON containing the pipeline properties definition.
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid runtime processor.

  /elyra/pipeline/export:
    post:
      tags:
        - pipeline
      summary: Export a pipeline.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineExportBodyPost'
      responses:
        201:
          description: The pipeline export response.
          headers:
            Location:
              description: The resource endpoint.
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                type: object
                properties:
                  export_path:
                    type: string
                    description: The pipeline export path.


  /elyra/pipeline/runtimes/types:
    get:
      tags:
        - pipeline
      summary: Get the set of static resources associated with currently configured runtime types
      responses:
        200:
          description: The resources associated with the currently configured runtime types
          content:
            application/json:
              schema:
                type: object
                properties:
                  runtime_types:
                    type: array
                    description: The list of resources associated with each configured runtime type.
                    items:
                      $ref: '#/components/schemas/RuntimeTypeResources'

  /elyra/pipeline/schedule:
    post:
      tags:
        - pipeline
      summary: Execute pipelines as batch jobs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineResource'
      responses:
        200:
          description: The pipeline processor response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineScheduleResponse'

  /elyra/pipeline/validate:
    post:
      tags:
        - pipeline
      summary: Validate a pipeline.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineResource'
      responses:
        200:
          description: The pipeline validation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineValidationResponse'


  /elyra/contents/properties/{filepath}:
    get:
      tags:
        - contents
      summary: Get a dictionary of properties for a file.
      parameters:
        - name: filepath
          in: path
          description: The path to the file to be parsed, relative to the JupyterLab server root directory.
          required: true
          schema:
            type: string
      responses:
        200:
          description: The dictionary of properties found while parsing the file.
          content:
            application/json:
              schema:
                type: object
                description: A dictionary of properties.
                allOf:
                  - $ref: '#/components/schemas/ContentsPropertiesResource'
        400:
          description: File is a directory.
        404:
          description: File not found.


components:
  schemas:
    MetadataResourceBody:
      description: The set of properties comprising the request body for POST and PUT requests.
      required:
        - display_name
        - schema_name
        - metadata
      type: object
      properties:
        name:
          type: string
          description: The canonical name of the resource.  Will be derived from display_name if not provided on POST.
        display_name:
          type: string
          description: The display name of the resource.
        schema_name:
          type: string
          description: The schema name used to validate the resource.
        metadata:
          type: object
          properties: {}
          description: A free-form dictionary consisting of additional information
            about the resource.

    MetadataResource:
      description: The set of properties comprising a metadata resource entity.
      required:
        - name
        - display_name
        - schema_name
        - metadata
      type: object
      properties:
        name:
          type: string
          description: The canonical name of the metadata resource.
        display_name:
          type: string
          description: The display name of the metadata resource.
        schema_name:
          type: string
          description: The schema name used to validate the metadata resource.
        metadata:
          type: object
          properties: {}
          description: A free-form dictionary consisting of additional information
            about the resource.

    SchemaResource:
      description: The set of properties comprising a schema resource entity.
      required:
        - name
        - schemaspace
      type: object
      properties:
        schemaspace:
          type: string
          description: The schemaspace name or id of the schema resource.
        name:
          type: string
          description: The canonical name of the schema resource.
        title:
          type: string
          description: The title of the schema resource.
        properties:
          type: object
          properties: {}
          description: A free-form dictionary consisting of additional information
            about the resource.

    SchemaspaceResource:
      description: The set of properties comprising a schemaspace resource entity.
      required:
        - name
        - id
        - display_name
        - description
      type: object
      properties:
        name:
          type: string
          description: The canonical name of the schemaspace resource.
        id:
          type: string
          description: The id of the schemaspace resource.
        display_name:
          type: string
          description: The display name of the schemaspace resource.
        description:
          type: string
          description: The description of the schemaspace resource.

    PipelineResource:
      description: The set of properties comprising a pipeline resource entity.
      required:
        - primary_pipeline
        - pipelines
      type: object
      properties:
        primary_pipeline:
          type: string
          description: The primary pipeline id.
        pipelines:
          type: array
          description: A set of pipeline definitions.
          items:
            type: object
            properties:
              id:
                type: string
                description: The unique identifier of the pipeline.
              name:
                type: string
                description: The name of the pipeline.
              nodes:
                type: array
                description: The set of nodes in the pipeline.
                items:
                  type: object
                  properties: {}
                  description: The node configuration.
              runtime:
                type: string
                description: The runtime type for the pipeline.
              runtime-config:
                type: object
                properties: {}
                description: The runtime configuration that should be used to submit the pipeline.

    PipelineScheduleResponse:
      description: The set of properties comprising a pipeline processor response entity.
      required:
        - run_url
        - object_storage_url
        - object_storage_path
      type: object
      properties:
        run_url:
          type: string
          description: The runtime URL to access the pipeline experiment.
        object_storage_url:
          type: string
          description: The object storage URL to access the pipeline outputs
            and processed notebooks.
        object_storage_path:
          type: string
          description: The object storage working directory path where the pipeline outputs
            and processed notebooks are located.

    PipelineExportBodyPost:
      description: The set of properties comprising the request body for POST request.
      required:
        - pipeline
        - export_format
        - export_path
        - overwrite
      type: object
      properties:
        pipeline:
          $ref: '#/components/schemas/PipelineResource'
        export_format:
          type: string
          description: The pipeline export format.
        export_path:
          type: string
          description: The pipeline export path.
        overwrite:
          type: boolean
          description: Determines if the existing export should be overwritten.

    PipelineValidationResponse:
      description: The set of properties comprising a pipeline validation response entity.
      required:
        - title
        - description
        - issues
      type: object
      properties:
        title:
          type: string
          description: The title relative to the validation response.
        description:
          type: string
          description: The description relative to the validation response.
        issues:
          type: array
          description: The issues encountered during validation.  This will be empty if no issues were encountered.
          items:
            type: object
            properties:
              severity:
                type: integer
                enum: [1, 2, 3, 4]
                description: The numeric value representing the severity of the issue - Error (1), Warning (2), Information (3), Hint (4)
              source:
                type: string
                description: The highlevel source of the validation issue.
              type:
                type: string
                description: Indicator of the category of the issue (e.g., "invalidNodeProperty", "invalidRuntime", etc.).
              message:
                type: string
                description: The message corresponding to the validation issue.
              data:
                type: object
                description: JSON consisting of information pertaining to where the issue occurred.

    RuntimeTypeResources:
      description: The set of properties comprising a runtime type resource entity.
      required:
        - id
        - display_name
        - icon
        - export_file_types
      type: object
      properties:
        id:
          type: string
          description: The id of the runtime type resource.
        display_name:
          type: string
          description: The display name of the runtime type resource.
        icon:
          type: string
          description: The location (endpoint) in which the runtime type icon can be found.
        export_file_types:
          type: array
          description: The set of export file types this runtime type supports.
          items:
            type: object
            properties:
              id:
                type: string
                description: The supported file suffix
              display_name:
                type: string
                description: The label corresponding to the export file type

    ContentsPropertiesResource:
      description: The set of resources comprising the request body.
      required:
        - env_vars
        - inputs
        - outputs
      type: object
      properties:
        env_vars:
          type: object
          description: A dictionary with a key for each environment variable name found and a value corresponding to the variable value or null.
          additionalProperties:
            type: string
        inputs:
          type: array
          description: A list of input file names.
          items:
            type: string
        outputs:
          type: array
          description: A list of output file names.
          items:
            type: string

    ComponentCacheResource:
      description: The request body for refreshing the component cache.
      required:
        - action
      type: object
      properties:
        action:
          type: string
          description: The action to carry out on the cache.  Only 'refresh' is supported.
          enum:
            - refresh