server-plugins-api.yaml

#  This program and the accompanying materials are
#  made available under the terms of the Eclipse Public License v2.0 which accompanies
#  this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html
#  
#  SPDX-License-Identifier: EPL-2.0
#  
#  Copyright Contributors to the Zowe Project.

swagger: "2.0"
info:
  description: "These are the Swagger documents on dynamic app server configuration for the Zowe desktop, used to control the plugin and services lifecycle. You can find more documentation about Zowe at [https://docs.zowe.org/stable/]."
  version: "1.0.0"
  title: "Zowe plugin and services lifecycle"
  license:
    name: "EPL-2.0"
host: "localhost"
basePath: /
tags:
- name: "server"
  description: "Server essentials"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/zowe/zlux-app-server"
- name: "plugins"
  description: "Plugin lifecycle changes"

schemes:
- "https"
- "http"
paths:

  /server/:
    get:
      tags:
      - "server"
      summary: "Retrieves list of accessible server endpoints"
      description: "Retrieves list of accessible server endpoints"
      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/serverLinksDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/agent:
    get:
      tags:
      - "server"
      summary: "Get the agent server (often ZSS server)"
      description: "Get the agent server (often ZSS server)"
      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/agent/config:
    get:
      tags:
      - "server"
      summary: "Get the config of the agent"
      description: "Get the config of the agent"

      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/agentConfigDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/agent/log:
    get:
      tags:
      - "server"
      summary: "Get the log of the agent"
      description: "Get the log of the agent"

      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/agent/logLevels:
    get:
      tags:
      - "server"
      summary: "Get the log of the agent"
      description: "Get the log of the agent"

      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/logLevelDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/agent/environment:
    get:
      tags:
      - "server"
      summary: "Get the log of the agent"
      description: "Get the log of the agent"

      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/agentEnvDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          

  /server/config:
    get:
      tags:
      - "server"
      summary: "Get the config of the server"
      description: "Get the config of the server"

      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/serverConfigDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"


  /server/config/attrib:
    post:
      tags:
      - "server"
      summary: "Update the config of the server, within the bounds of allowed attributes, one attribute at a time (including whole attribute objects)."
      description: "Update the config of the server, within the bounds of allowed attributes, one attribute at a time (including whole attribute objects)."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "attrib"
        schema:
            $ref: "#/definitions/allowedConfigChangesDefinition"
        description: "Update allowed attributes of server config via JSON post body. Attribute must be '.' separated query and cannot contain an array index."
        required: true
      responses:
        200:
          description: "Port remapped to ${req.params.port}"
        401:
          description: "Unauthorized"
        400:
          description: "Port query expected positive integer, received ${req.params.port}\n\nOR\n\nPort query expected positive integer, received ${req.params.port}\n\nOR\n\nServer must be running in cluster mode to remap http(s) port"
        500:
          description: "Unable to update server configuration file"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"

  /server/environment:
    get:
      tags:
      - "server"
      summary: "Get environment variables of the server"
      description: "Get environment variables of the server"
      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/serverEnvDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"

  /server/log:
    get:
      tags:
      - "server"
      summary: "Retrieve the server log"
      description: "Retrieve the server log"
      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
        401:
          description: "Unauthorized"
        501:
          description: "Log not found"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/logLevels:
    get:
      tags:
      - "server"
      summary: "Get the log levels of the server and plugins"
      description: "Get the log levels of the server and plugins"
      produces:
      - "application/json"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/logLevelDefinition"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/logLevels/name/:componentName/level/:level:
    post:
      tags:
      - "server"
      summary: "Set the log 'level' using the component 'name' of a logger"
      description: "Set the log 'level' using the component 'name' of a logger"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "componentName"
        description: "Logger component name"
        type: "string"
        required: true
      - in: "query"
        name: "level"
        description: "Logger level (default 0 - 5)"
        type: "number"
        required: true
      responses:
        200:
          description: "Success"
        400:
          description: "Log level must be a number\n\nOR\n\nLog level must be within the accepted levels of 'MIN' and 'MAX'"
        401:
          description: "Unauthorized"
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  # /server/logLevels/pattern/:componentPattern/level/:level:
  #   post:
  #     tags:
  #     - "server"
  #     summary: "Set the log levels of a logger using a RegEx 'pattern'"
  #     description: "Set the log levels of a logger using a RegEx 'pattern'"
  #     produces:
  #     - "application/json"
  #     parameters:
  #     - in: "query"
  #       name: "pattern"
  #       description: "Logger component pattern"
  #       type: "string"
  #       required: true
  #     responses:
  #       200:
  #         description: "Success"
  #       400:
  #         description: "Log level must be a number\n\nOR\n\nLog level must be within the accepted levels of 'MIN' and 'MAX'"
  #       401:
  #         description: "Unauthorized"
  #       506:
  #         description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /server/reload:
    get:
      tags:
      - "server"
      summary: "(Cluster only) Reloads the server"
      description: "(Cluster only) Reloads the server"
      produces:
      - "application/json"
      responses:
        200:
          description: "Reloading server, please wait a moment."
        401:
          description: "Unauthorized"
        500:
          description: "Cannot reload server unless cluster mode is in use."
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
  /plugins/:
    get:
      tags:
      - "plugins"
      summary: "Gets list of plugins and their dataservices"
      description: "Gets list of plugins and their dataservices"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "plugin type"
        description: "Type of plugins to query. Default is 'all'"
        type: "string"
        required: true
      responses:
        200:
          description: "Success"
          schema:
              $ref: "#/definitions/pluginsDefinition"
        401:
          description: "Unauthorized"
    put:
      tags:
      - "plugins"
      summary: "(Cluster only) Add a plugin (or upgrade an existing one) to the server via 'location'"
      description: "(Cluster only) Add a plugin (or upgrade an existing one) to the server via 'location'"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "plugin location"
        description: "Location in the local file system"
        type: "string"
        required: true
      responses:
        200:
          description: "Successfully installed '${installResponse.message}'. Reloading server, please wait a moment."
        400:
          description: "Failed to install plugin.  Error: ${installResponse.message}\n\nOR\n\nPath query must be a directory.\n\nOR\n\nName queries not yet supported.\n\nOR\n\n"
        401:
          description: "Unauthorized"
        500:
          description: "Could not complete new plugin scan."
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
      
  /plugins/:id:
    delete:
      tags:
      - "plugins"
      summary: "(Cluster only) Deletes a plugin 'identifier' and reloads the server"
      description: "(Cluster only) Deletes a plugin 'identifier' and reloads the server"
      produces:
      - "application/json"
      parameters:
      - name: "Plugin identifier"
        in: "query"
        type: "string"
        required: true
      responses:
        200:
          description: "Deleting plugin 'identifier'. Reloading server, please wait a moment."
        400:
          description: "${fullPath} does not exist.\n\nOR\n\nImproper access permissions for path '${fullPath}'\n\nOR\n\n${err}"
        401:
          description: "Unauthorized"
        500:
          description: "Cannot reload server unless cluster mode is in use."
        506:
          description: "Set dataserviceAuthentication.rbac to true in server configuration"
          
      
definitions:
  pluginsDefinition:
    type: "array"
    items:
      type: "object"
      properties:
        identifier:
          type: "string"
        pluginVersion:
          type: "string"
        apiVersion:
          type: "string"
        pluginType:
          type: "string"
        copyright:
          type: "string"
        webContent:
          type: "object"
        configurationData:
          type: "object"
          properties:
            resources:
              type: "object"
        dataServices:
          type: "object"
          properties:
            configuration:
              type: "object"
              properties:
                contents:
                  type: "object"
            type:
              type: "string"
            sourceName:
              type: "string"
            localName:
              type: "string"
            sourcePlugin:
              type: "string"
            versionRange:
              type: "string"
            version:
              type: "string"
  
  serverEnvDefinition:
    type: "object"
    properties:
      timestamp:
        type: "string"
      args:
        type: "string"
      nodeArgs:
        type: "string"
      platform:
        type: "string"
      arch:
        type: "string"
      osRelease:
        type: "object"
      cpus:
        type: "array"
        items:
          type: "object"
      freeMemory:
        type: "number"
      hostname:
        type: "string"
      userEnvironment:
        type: "object"
      PID:
        type: "number"
      PPID:
        type: "number"
      nodeVersion:
        type: "string"
      nodeRelease:
        type: "object"
        
  agentEnvDefinition:
    type: "object"
    properties:
      timestamp:
        type: "string"
      logDirectory:
        type: "string"
      agentName:
        type: "string"
      agentVersion:
        type: "string"
      arch:
        type: "string"
      osRelease:
        type: "string"
      osVersion:
        type: "string"
      hardwareIdentifier:
        type: "string"
      hostname:
        type: "string"
      nodename:
        type: "string"
      userEnvironment:
        type: "object"
      demandPagingRate:
        type: "number"
      stdCP_CPU_Util:
        type: "number"
      stdCP_MVS_SRM_CPU_Util:
        type: "number"
      ZAAP_CPU_Util:
        type: "number"
      ZIIP_CPU_Util:
        type: "number"
      PID:
        type: "number"
      PPID:
        type: "number"
        
  logLevelDefinition:
    type: "object"
    properties:
      logComponentName:
        type: "number"
        
  serverLinksDefinition:
    type: "object"
    properties:
      links:
        type: "array"
        items:
          type: "object"
          properties:
            href:
              type: "string"
            rel:
              type: "string"
            type:
              type: "string"
      
            
  serverConfigDefinition:
    type: "object"
    properties:
      options:
        type: "object"
        properties:
          rootDir:
            type: "string"
          productDir:
            type: "string"
          siteDir: 
            type: "string"
          instanceDir:
            type: "string"
          groupsDir:
            type: "string"
          usersDir:
            type: "string"
          pluginsDir:
            type: "string"
          node:
            type: "object"
            properties:
              https:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
                  keys:
                    type: "array"
                    items:
                      type: "string"
                  certificates:
                    type: "array"
                    items:
                      type: "string"
                  certificateAuthorities:
                    type: "array"
                    items:
                      type: "string"
                  enabled:
                    type: "boolean"
              mediationLayer:
                type: "object"
                properties:
                  server:
                    type: "object"
                    properties:
                      hostname:
                        type: "string"
                      port:
                        type: "number"
                      isHttps:
                        type: boolean
                  enabled:
                    type: boolean
              childProcesses:
                type: "object"
          dataserviceAuthentication:
            type: "object"
            properties:
              defaultAthentication:
                type: "string"
              rbac:
                type: boolean
              implementationDefaults:
                type: "object"
          agent:
            type: "object"
            properties:
              host:
                type: "string"
              http:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
          zssPort:
            type: "number"
          logLanguage:
            type: "string"
          logLevels:
            type: "object"
            
  agentConfigDefinition:
    type: "object"
    properties:
      options:
        type: "object"
        properties:
          node:
            type: "object"
            properties:
              https:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
                  keys:
                    type: "array"
                    items:
                      type: "string"
                  certificates:
                    type: "array"
                    items:
                      type: "string"
                  certificateAuthorities:
                    type: "array"
                    items:
                      type: "string"
                  enabled:
                    type: "boolean"
              mediationLayer:
                type: "object"
                properties:
                  server:
                    type: "object"
                    properties:
                      hostname:
                        type: "string"
                      port:
                        type: "number"
                      isHttps:
                        type: boolean
                  enabled:
                    type: boolean
              childProcesses:
                type: "object"
          agent:
            type: "object"
            properties:
              host:
                type: "string"
              http:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
          rootDir:
            type: "string"
          productDir:
            type: "string"
          siteDir: 
            type: "string"
          instanceDir:
            type: "string"
          groupsDir:
            type: "string"
          usersDir:
            type: "string"
          pluginsDir:
            type: "string"
          dataserviceAuthentication:
            type: "object"
            properties:
              defaultAthentication:
                type: "string"
              rbac:
                type: boolean
              implementationDefaults:
                type: "object"
          zssPort:
            type: "number"
          logLanguage:
            type: "string"
          logLevels:
            type: "object"
            
  allowedConfigChangesDefinition:
    type: "object"
    properties:
      options:
        type: "object"
        properties:
          node:
            type: "object"
            properties:
              allowInvalidTLSProxy: 
                type: "object"
              noPrompt:
                type: "object"
              noChild:
                type: "object"
              https:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
              mediationLayer:
                type: "object"
                properties:
                  server:
                    type: "object"
                    properties:
                      hostname:
                        type: "string"
                      port:
                        type: "number"
                      isHttps:
                        type: boolean
                  enabled:
                    type: boolean
              childProcesses:
                type: "object"
          dataserviceAuthentication:
            type: "object"
            properties:
              defaultAthentication:
                type: "string"
              rbac:
                type: boolean
              implementationDefaults:
                type: "object"
          agent:
            type: "object"
            properties:
              host:
                type: "string"
              http:
                type: "object"
                properties:
                  ipAddresses:
                    type: "array"
                    items:
                      type: "string"
                  port:
                    type: "number"
          zssPort:
            type: "number"
          logLanguage:
            type: "string"
          logLevels:
            type: "object"
            
            
externalDocs:
  description: "Find out more about Zowe"
  url: "https://www.zowe.org/"