odo/ododevapispec.yaml

openapi: '3.0.2'
info:
  title: odo dev
  version: '0.1'
  description: API interface for 'odo dev'
servers:
  - url: /api/v1
paths:
  /instance:
    get:
      description: Get information about the this 'odo dev' instance.
      responses:
        '200':
          description: Information about the this 'odo dev' instance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  componentDirectory:
                    type: string
                    description: Directory on which this 'odo dev' instance is running
                  pid:
                    type: integer
                    description: PID of the this 'odo dev' instance.
              example:
                componentDirectory: "/Users/user/Documents/myproject"
                pid: 42

    delete:
      description: "Stop this 'odo dev' instance"
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSuccess'
              example:
                message: "'odo dev' instance with pid: 42 is shuting down."
          description: "'odo dev' instance will shutdown."

  /component:
    get:
      description: Get the Information about the component controlled by this 'odo dev' instance.
      responses:
        '200':
          description: Information about the component.
          content:
            application/json:
              schema:
                type: object
                properties:
                  component:
                    type: object
                    description: Description of the component. This is the same as output of 'odo describe component -o json'
              example:
                {
                  "devfilePath": "/home/tomas/Code/odo-examples/java-maven/devfile.yaml",
                  "devfileData": {
                          "devfile": {
                                  "schemaVersion": "2.1.0",
                                  "metadata": {
                                          "name": "demo",
                                          "version": "1.1.1",
                                          "displayName": "Maven Java",
                                          "description": "Upstream Maven and OpenJDK 11",
                                          "tags": [
                                                  "Java",
                                                  "Maven"
                                          ],
                                          "icon": "https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/java-maven.jpg",
                                          "projectType": "Maven",
                                          "language": "Java"
                                  },
                                  "components": [
                                          {
                                                  "name": "tools",
                                                  "container": {
                                                          "image": "quay.io/eclipse/che-java11-maven:next",
                                                          "env": [
                                                                  {
                                                                          "name": "DEBUG_PORT",
                                                                          "value": "5858"
                                                                  }
                                                          ],
                                                          "volumeMounts": [
                                                                  {
                                                                          "name": "m2",
                                                                          "path": "/home/user/.m2"
                                                                  }
                                                          ],
                                                          "memoryLimit": "512Mi",
                                                          "mountSources": true,
                                                          "dedicatedPod": false,
                                                          "endpoints": [
                                                                  {
                                                                          "name": "http-maven",
                                                                          "targetPort": 8080,
                                                                          "secure": false
                                                                  }
                                                          ]
                                                  }
                                          },
                                          {
                                                  "name": "m2",
                                                  "volume": {
                                                          "ephemeral": false
                                                  }
                                          }
                                  ],
                                  "starterProjects": [
                                          {
                                                  "name": "springbootproject",
                                                  "git": {
                                                          "remotes": {
                                                                  "origin": "https://github.com/odo-devfiles/springboot-ex.git"
                                                          }
                                                  }
                                          }
                                  ],
                                  "commands": [
                                          {
                                                  "id": "mvn-package",
                                                  "exec": {
                                                          "group": {
                                                                  "kind": "build",
                                                                  "isDefault": true
                                                          },
                                                          "commandLine": "mvn -Dmaven.repo.local=/home/user/.m2/repository package",
                                                          "component": "tools",
                                                          "workingDir": "${PROJECT_SOURCE}",
                                                          "hotReloadCapable": false
                                                  }
                                          },
                                          {
                                                  "id": "run",
                                                  "exec": {
                                                          "group": {
                                                                  "kind": "run",
                                                                  "isDefault": true
                                                          },
                                                          "commandLine": "java -jar target/*.jar",
                                                          "component": "tools",
                                                          "workingDir": "${PROJECT_SOURCE}",
                                                          "hotReloadCapable": false
                                                  }
                                          },
                                          {
                                                  "id": "debug",
                                                  "exec": {
                                                          "group": {
                                                                  "kind": "debug",
                                                                  "isDefault": true
                                                          },
                                                          "commandLine": "java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=${DEBUG_PORT},suspend=n -jar target/*.jar",
                                                          "component": "tools",
                                                          "workingDir": "${PROJECT_SOURCE}",
                                                          "hotReloadCapable": false
                                                  }
                                          }
                                  ]
                          },
                          "supportedOdoFeatures": {
                                  "dev": true,
                                  "deploy": false,
                                  "debug": true
                          }
                  },
                  "runningIn": {
                          "deploy": false,
                          "dev": true
                  },
                  "managedBy": "odo"
               }
        '500':
          description: error getting the description of the component
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                message: "error getting the description of the component"

  /component/command:
    post:
      description: Instruct 'odo dev' to perform given command on the component
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the command that should be executed
                  type: string
                  enum:
                    - "push"
              example:
                name: push
      responses:
        '200':
          description: command was successfully executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSuccess'
              example:
                message: "push was successfully executed"
        '400':
          description: command name not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                message: "command name 'unknown' not supported. Supported values are: \"push\""
        '429':
          description: a push operation is not possible at this time. Please retry later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                message: "a push operation is not possible at this time. Please retry later"

components:
  schemas:
    GeneralSuccess:
      type: object
      properties:
        message:
          type: string
    GeneralError:
      type: object
      properties:
        message:
          type: string