Submarine Swagger API definition

submarineAPI.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/status"
  version: "1.0.0"
  title: "Submarine Job 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: "jobs"
  description: "Everything about your Jobs"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/apache/submarine/"
schemes:
- "https"
- "http"
paths:
  /jobs:
    post:
      tags:
      - "jobs"
      summary: "Submit a job to server"
      description: ""
      operationId: "createJob"
      consumes:
      - "application/json"
      - "application/yaml"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Submarine job spec"
        required: true
        schema:
          $ref: "#/definitions/JobSpec"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        405:
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:jobs"
        - "read:jobs"
    get:
      tags:
      - "jobs"
      summary: "List all jobs"
      description: "List all job in submarine server"
      operationId: "listJobs"
      produces:
      - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ApiResponse"
        400:
          description: "Invalid status value"
      security:
      - petstore_auth:
        - "write:jobs"
        - "read:jobs"
  /jobs/{jobId}:
    get:
      tags:
      - "jobs"
      summary: "Find job by ID"
      description: "Returns a single job"
      operationId: "getJobById"
      produces:
      - "application/json"
      parameters:
      - name: "jobId"
        in: "path"
        description: "ID of pet to return"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Job not found"
      security:
      - api_key: []
    post:
      tags:
      - "jobs"
      summary: "Updates a job in the submarine server with job spec"
      description: ""
      operationId: "updatePetWithJobSpec"
      consumes:
      - "application/json"
      - "application/yaml"
      produces:
      - "application/json"
      parameters:
      - name: "jobId"
        in: "path"
        description: "ID of pet to return"
        required: true
        type: "integer"
        format: "int64"
      - in: "body"
        name: "body"
        description: "Submarine job spec"
        required: true
        schema:
          $ref: "#/definitions/job"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        405:
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:jobs"
        - "read:jobs"
    delete:
      tags:
      - "jobs"
      summary: "Deletes a job"
      description: ""
      operationId: "deleteJob"
      produces:
      - "application/json"
      parameters:
      - name: "jobId"
        in: "path"
        description: "Job id to delete"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Job not found"
      security:
      - petstore_auth:
        - "write:jobs"
        - "read:jobs"
securityDefinitions: # TODO
  petstore_auth:
    type: "oauth2"
    authorizationUrl: "http://petstore.swagger.io/oauth/dialog"
    flow: "implicit"
    scopes:
      write:jobs: "modify pets in your account"
      read:jobs: "read your pets"
  api_key:
    type: "apiKey"
    name: "api_key"
    in: "header"
definitions:
  job:
    type: "object"
    properties:
      jobId:
        type: string
      name:
        type: string
      uid:
        type: string
      status:
        type: string
      acceptedTime:
        type: string
      createdTime:
        type: string
      runningTime:
        type: string
      finishedTime:
        type: string
      jobSpec:
        $ref: "#/definitions/JobSpec"
  JobSpec:
     type: "object"
     required:
     - "name"
     - "librarySpec"
     - "submitterSpec"
     - "taskSpecs"
     properties:
      name:
        type: "string"
      librarySpec:
        $ref: "#/definitions/LibrarySpec"
      submitterSpec:
        $ref: "#/definitions/SubmitterSpec"
      taskSpecs:
        type: "object"
        properties:
          Ps:
            $ref: "#/definitions/TaskSpec"
          Worker:
            $ref: "#/definitions/TaskSpec"
          Chief:
            $ref: "#/definitions/TaskSpec"
        required:
        - Worker
  LibrarySpec:
    type: "object"
    required:
     - "name"
     - "version"
     - "image"
    properties:
      name:
        type: "string"
        description: "Machine Learning Framework name. Only tensorflow and pytorch is supported. It doesn't matter if the value is uppercase or lowercase."
      version:
        type: "string"
        description: "The version of ML framework. Such as: 2.1.0"
      image:
        type: "string"
        description: "The public image used for each task if not specified. Such as: apache/submarine"
      cmd: 
        type: "string"
        description: "The public entry cmd for the task if not specified"
      envVars: 
        type: "object"
        description: "The public env vars for the task if not specified."
        additionalProperties:
          type: string
        example:
          "JAVA_HOME": "/opt/java"
  SubmitterSpec:
    type: "object"
    required:
     - "type"
     - "namespace"
    properties:
      type:
        type: "string"
        description: "The submitter type, supports k8s now."
      configPath:
        type: "string"
        description: "The config path of the specified resource manager. You can set it in submarine-site.xml if run submarine-server locally"
      namespace:
        type: "string"
        description: "It's known as queue in Apache Hadoop YARN and namespace in Kubernetes."
      kind: 
        type: "string"
        description: "It's used for k8s submitter, supports TFJob and PyTorchJob"
      apiVersion:
        type: "string"
        description: "It should pair with the kind, such as the TFJob's api version is kubeflow.org/v1"
  TaskSpec:
    type: "object"
    required:
     - "resources"
    properties:
      name:
        type: "string"
        description: "The job task name, if not specify using the library name"
      image:
        type: "string"
        description: "The job task image"
      cmd:
        type: "string"
        description: "The entry command for running task"
      envVars: 
        type: "object"
        description: "The env vars for the task"
        additionalProperties:
          type: string
        example:
          "JAVA_HOME": "/opt/java"
      resources:
        type: "string"
        description: "The limit resource for the task. Formatter: cpu=%s,memory=%s,nvidia.com/gpu=%s"
  ApiResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      status:
        type: "string"
      success:
        type: "string"
      message:
        type: "string"
      result:
        $ref: "#/definitions/job"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"