Submarine Experiment spec - swagger 2.0

experiment.yaml

swagger: "2.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"
host: "localhost:8080"
basePath: "/api/v1"
tags:
- name: "experiment"
  description: "Everything about your Jobs"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/apache/submarine/"
schemes:
- "https"
- "http"
paths:
  /experiment:
    post:
      tags:
      - "experiment"
      summary: "Create the experiment"
      description: ""
      operationId: "createExperiment"
      consumes:
      - "application/json"
      - "application/yaml"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Submarine experiment spec"
        required: true
        schema:
          $ref: "#/definitions/ExperimentSpec"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
    get:
      tags:
      - "experiment"
      summary: "List all experiments"
      description: "List all experiment in submarine server"
      operationId: "listExperiments"
      produces:
      - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ApiResponse"
  /experiment/{experimentId}:
    get:
      tags:
      - "experiment"
      summary: "Find the experiment by id"
      description: "Returns a single experiment"
      operationId: "getExperimentById"
      produces:
      - "application/json"
      parameters:
      - name: "experimentId"
        in: "path"
        description: "ID of pet to return"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        404:
          description: "Experiment not found"
    post:
      tags:
      - "experiment"
      summary: "Update the experiment in the submarine server with experiment spec"
      description: ""
      operationId: "updateExperimentWitheExperimentSpec"
      consumes:
      - "application/json"
      - "application/yaml"
      produces:
      - "application/json"
      parameters:
      - name: "experimentId"
        in: "path"
        description: "ID of pet to return"
        required: true
        type: "integer"
        format: "int64"
      - in: "body"
        name: "body"
        description: "Submarine experiment spec"
        required: true
        schema:
          $ref: "#/definitions/experiment"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
    delete:
      tags:
      - "experiment"
      summary: "Deletes a experiment"
      description: ""
      operationId: "deleteExperiment"
      produces:
      - "application/json"
      parameters:
      - name: "experimentId"
        in: "path"
        description: "Experiment id to delete"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        404:
          description: "Experiment not found"
definitions:
  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: "#/definitions/ExperimentSpec"
  ExperimentSpec:
     type: "object"
     required:
     - "name"
     - "taskSpecs"
     properties:
      name:
        type: "string"
      type:
        type: "string"
        enum: 
        - "AdhocSpec"
        - "PredefinedSpec"
      spec:
        type: "object"
        description: "The env vars for the task"
        properties:
          adhocSpec:
            $ref: "#/definitions/AdhocSpec"
          predefinedSpec:
            $ref: "#/definitions/PredefinedSpec"
      code:
        $ref: "#/definitions/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"
      scripSpec:
        $ref: "#/definitions/ScriptSpec"
      distributedTensorflowSpec:
        $ref: "#/definitions/DistributedTensorflowSpec"
      distributedPyTorchSpec:
        $ref: "#/definitions/DistributedPyTorchSpec"
  PredefinedSpec: # TBD
     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: "#/definitions/ResourceSpec"
      num_worker:
        type: "integer"
        description: "Number of workers when running distrubuted training"
      worker_resources:
        $ref: "#/definitions/ResourceSpec"
      num_chief:
        type: "integer"
        description: "Number of chiefs when running distrubuted training"
      chief_resources:
        $ref: "#/definitions/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: "#/definitions/ResourceSpec"
  DistributedTensorflowSpec:
    type: "object"
    required:
    - Worker
    - Ps
    properties:
      Ps:
        $ref: "#/definitions/ScriptSpec"
      Worker:
        $ref: "#/definitions/ScriptSpec"
      Chief:
        $ref: "#/definitions/ScriptSpec"
  DistributedPyTorchSpec:
    type: "object"
    required:
    - Worker
    properties:
      Worker:
        $ref: "#/definitions/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: "#/definitions/experiment"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"