openapi.yml

openapi: "3.0.0"
info:
  title: "node-server-manager"
  description: "A new service control engine, built on docker."
  contact:
    name: "ZorTik"
    url: "https://zortik.vercel.app"
  version: "0.0.1"

components:
  schemas:
    Status:
      type: "object"
      properties:
        nodeId:
          type: "string"
        running:
          type: "array"
          items:
            type: "string"
        all:
          type: "integer"
          format: "int32"
          minimum: 0
        system:
          type: "object"
          properties:
            totalmem:
              type: "number"
              format: "int32"
            freemem:
              type: "number"
              format: "int32"
            totaldisk:
              type: "number"
              format: "int32"
            freedisk:
              type: "number"
              format: "int32"
        stats:
          type: "object"
          description: "The momentary resource stats collected from NSM services ONLY. If ?stats=true, default is false."
          properties:
            memory:
              type: "object"
              properties:
                used:
                  type: "number"
                total:
                  type: "number"
                percent:
                  type: "number"
            cpu:
              type: "object"
              properties:
                used:
                  type: "number"
                total:
                  type: "number"
                percent:
                  type: "number"
            services:
              type: "object"
              properties:
                memTotal:
                  type: "number"
                  description: "Total memory registered (limit, not in use) by all services"
                cpuTotal:
                  type: "number"
                  description: "Total CPU registered (limit, not in use) by all services"
                diskTotal:
                  type: "number"
                  description: "Total disk registered (limit, not in use) by all services"
    Result:
      type: "object"
      properties:
        status:
          type: "integer"
          format: "int32"
        message:
          type: "string"
        statusPath:
          type: "string"
          description: "The PATH to check the status of the service. (Optional)"
    SessionInfo:
      type: "object"
      description: "The session information about a running service, if running"
      properties:
        serviceId:
          type: "string"
        nodeId:
          type: "string"
        containerId:
          type: "string"
        stats:
          type: "object"
          properties:
            id:
              type: "string"
            memory:
              type: "object"
              properties:
                used:
                  type: "number"
                total:
                  type: "number"
                percent:
                  type: "number"
            cpu:
              type: "object"
              properties:
                used:
                  type: "number"
                total:
                  type: "number"
                percent:
                  type: "number"
    TemplateLookup:
      type: "object"
      properties:
        id:
          type: "string"
          description: "The template ID (often folder name)"
        name:
          type: "string"
          description: "The template name, from settings.yml"
        description:
          type: "string"
          description: "The template description, from settings.yml"
        settings:
          type: "object"
          description: "The settings from settings.yml"
    ServiceLookup:
      type: "object"
      properties:
        id:
          type: "string"
          description: "The service UID in the system"
        template:
          $ref: "#/components/schemas/TemplateLookup"
        port:
          type: "integer"
          format: "int32"
          description: "The main port number od the service"
        options:
          type: "object"
          description: "The options values used to create the service, or defaults from settings.yml apply"
        env:
          type: "object"
          description: "The custom variables mapped to values whose definitions are in settings.yml in template under 'env'"
        session:
          $ref: "#/components/schemas/SessionInfo"
    ServiceCreateOptions:
      type: "object"
      properties:
        template:
          type: string
          required: true
          description: "The template ID"
        ram:
          type: integer
          format: int32
          required: false
          description: "RAM limit, in bytes"
        cpu:
          type: integer
          format: int32
          required: false
          description: "CPU limit, in cores"
        disk:
          type: integer
          format: int32
          required: false
          description: "Disk limit, in bytes"
        env:
          type: object
          required: false
          description: "A map of custom variables mapped to values whose definitions are in settings.yml in template under 'env'."
paths:
  /v1/status:
    get:
      description: "Get status of the engine"
      parameters:
        - name: "stats"
          in: "query"
          description: "Whether or not to include momentary resource stats. Default: false"
          schema:
            type: "boolean"
      responses:
        "200":
          description: "The status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
  /v1/servicelist:
    post:
      description: "Get list of services"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                page:
                  type: "integer"
                  format: "int32"
                  description: "The page index"
                pageSize:
                  type: "integer"
                  format: "int32"
                  description: "The page size"
                all:
                  type: "boolean"
                  description: "Whether or not we should include services from other nodes."
                  required: false
      responses:
        "200":
          description: "List of service IDs"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  services:
                    type: "array"
                    items:
                      type: "string"
                  meta:
                    type: "object"
                    properties:
                      page:
                        type: "integer"
                        format: "int32"
                      pageSize:
                        type: "integer"
                        format: "int32"
                      total:
                        type: "integer"
                        format: "int32"
  /v1/service/create:
    post:
      description: "Create a new service"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceCreateOptions"
      responses:
        "200":
          description: "Successfully created and started service."
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: "integer"
                    format: "int32"
                  message:
                    type: "string"
                  serviceId:
                    type: "string"
                    description: "The service UID in the system"
                  statusPath:
                    type: "string"
                    description: "The PATH to check the status of the service"
                  time:
                    type: "integer"
                    format: "int32"
                    description: "The time taken to create and start the service, in milliseconds"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}:
    get:
      description: "Get service details"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
        - name: "stats"
          in: "query"
          description: "Whether or not to include momentary resource stats. Default: false"
          schema:
            type: "boolean"
      responses:
        "200":
          description: "The service details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceLookup"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/resume:
    post:
      description: "Resume a service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successfully resumed service."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "409":
          description: "Conflict, service is already running"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/stop:
    post:
      description: "Stop a service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
        - name: "force"
          in: "query"
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: "Successfully stopped service."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "409":
          description: "Conflict, service is not running"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/stopcmd:
    post:
      description: "Stop a service using cmd"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Stop command successfully sent."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "409":
          description: "Conflict, service is not running"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/delete:
    post:
      description: "Delete a service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successfully deleted service."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/reboot:
    post:
      description: "Reboot a service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successfully rebooted service."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/powerstatus:
    get:
      description: "Get power status (state) of a pending service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "The power status"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  id:
                    type: "string"
                    description: "The service UID in the system"
                  status:
                    type: "string"
                    description: "The power status. One of: 'IDLE', 'PENDING', 'ERROR'."
                  error:
                    type: "string"
                    description: "The error message, if status is 'ERROR'."
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
  /v1/service/{serviceId}/options:
    post:
      description: "Update build options of a service"
      parameters:
        - name: "serviceId"
          in: "path"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceCreateOptions"
      responses:
        "200":
          description: "Successfully updated options."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "404":
          description: "Service not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"