Submarine API definition - OpenAPI 3.0

experiment_openapi3.yaml

openapi: 3.0.0
info:
  description: The Submarine REST API allows you to create, list, and get experiments. The
    API is hosted under the /v1/jobs route on the Submarine server. For example,
    to list experiments on a server hosted at http://localhost:8080, access
    http://localhost:8080/api/v1/jobs/
  version: 1.0.0
  title: Submarine Experiment API
  termsOfService: http://swagger.io/terms/
  contact:
    email: submarine-dev@submarine.apache.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: experiment
    description: Everything about your Jobs
    externalDocs:
      description: Find out more
      url: https://github.com/apache/submarine/
paths:
  /experiment:
    post:
      tags:
        - experiment
      summary: Create the experiment
      description: ""
      operationId: createExperiment
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExperimentSpec"
          application/yaml:
            schema:
              $ref: "#/components/schemas/ExperimentSpec"
        description: Submarine experiment spec
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - experiment
      summary: List all experiments
      description: List all experiment in submarine server
      operationId: listExperiments
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiResponse"
  "/experiment/{experimentId}":
    get:
      tags:
        - experiment
      summary: Find the experiment by id
      description: Returns a single experiment
      operationId: getExperimentById
      parameters:
        - name: experimentId
          in: path
          description: ID of pet to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Experiment not found
    post:
      tags:
        - experiment
      summary: Update the experiment in the submarine server with experiment spec
      description: ""
      operationId: updateExperimentWitheExperimentSpec
      parameters:
        - name: experimentId
          in: path
          description: ID of pet to return
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/experiment"
          application/yaml:
            schema:
              $ref: "#/components/schemas/experiment"
        description: Submarine experiment spec
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - experiment
      summary: Deletes a experiment
      description: ""
      operationId: deleteExperiment
      parameters:
        - name: experimentId
          in: path
          description: Experiment id to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Experiment not found
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: https://localhost:8080/api/v1
  - url: http://localhost:8080/api/v1
components:
  schemas:
    experiment:
      type: object
      properties:
        experimentId:
          type: string
        name:
          type: string
        uid:
          type: string
        status:
          type: string
        acceptedTime:
          type: string
        createdTime:
          type: string
        runningTime:
          type: string
        finishedTime:
          type: string
        experimentSpec:
          $ref: "#/components/schemas/ExperimentSpec"
    ExperimentSpec:
      type: object
      required:
        - name
        - taskSpecs
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - AdhocSpec
            - PredefinedSpec
        spec:
          oneOf:
          - $ref: "#/components/schemas/AdhocSpec"
          - $ref: "#/components/schemas/PredefinedSpec"
        code:
          $ref: "#/components/schemas/codeSpec"
        tensorboard:
          type: boolean
        timeout:
          type: string
          example: 30m
    AdhocSpec:
      type: object
      required:
        - name
        - taskSpecs
        - kind
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - Script
            - DistributedTensorflow
            - DistributedPyTorch
        kind:
          oneOf:
          - $ref: "#/components/schemas/ScriptSpec"
          - $ref: "#/components/schemas/DistributedTensorflowSpec"
          - $ref: "#/components/schemas/DistributedPyTorchSpec"
    PredefinedSpec:
      type: object
      required:
        - name
        - taskSpecs
        - intputParameters
        - traingParameters
        - resourceParameters
      properties:
        name:
          type: string
        environment:
          type: string
        parameters:
          type: array
          example:
            - name: input.train_data
              required: true
              description: train data is expected in SVM, and can be stored in HDFS/S3
            - name: training.batch_size
              required: false
              default: 32
              description: This is batch size of training
          items:
            type: object
            properties:
              name:
                type: string
              required:
                type: boolean
              default:
                type: string
                description: When required = false, a default value can be provided by the
                  template
              description:
                type: string
                description: Description of the parameter
        num_ps:
          type: integer
          description: Number of parameter servers when running distrubuted training
        ps_resources:
          $ref: "#/components/schemas/ResourceSpec"
        num_worker:
          type: integer
          description: Number of workers when running distrubuted training
        worker_resources:
          $ref: "#/components/schemas/ResourceSpec"
        num_chief:
          type: integer
          description: Number of chiefs when running distrubuted training
        chief_resources:
          $ref: "#/components/schemas/ResourceSpec"
    ScriptSpec:
      type: object
      required:
        - resources
      properties:
        name:
          type: string
          description: The experiment task name, if not specify using the library name
        environment:
          type: string
        cmd:
          type: array
          description: The entry command for running task
          items:
            type: string
          example:
            - python
            - training.py
            - --iteration
            - "10"
            - --input=s3://bucket/input
            - output=s3://bucket/output
        envVars:
          type: object
          description: The env vars for the task
          additionalProperties:
            type: string
          example:
            JAVA_HOME: /opt/java
        resources:
          $ref: "#/components/schemas/ResourceSpec"
    DistributedTensorflowSpec:
      type: object
      required:
        - Worker
        - Ps
      properties:
        Ps:
          $ref: "#/components/schemas/ScriptSpec"
        Worker:
          $ref: "#/components/schemas/ScriptSpec"
        Chief:
          $ref: "#/components/schemas/ScriptSpec"
    DistributedPyTorchSpec:
      type: object
      required:
        - Worker
      properties:
        Worker:
          $ref: "#/components/schemas/ScriptSpec"
    codeSpec:
      type: object
      properties:
        sync_mode:
          type: string
        url:
          type: string
    ResourceSpec:
      type: object
      required:
        - memory
        - vcore
      properties:
        memory:
          type: string
          example: 20gb
        vcore:
          type: string
          example: "3"
        gpu:
          type: string
          example: "2"
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        status:
          type: string
        success:
          type: string
        message:
          type: string
        result:
          $ref: "#/components/schemas/experiment"