on-http-y1/static/monorail-2.0-sb.yaml

OnRack Http Server

swagger: "2.0"
info:
  version: "0.0.1"
  title: RackHD 2.0 Southbound
# during dev, should point to your local machine
#host: localhost:10010
# basePath prefixes all resource paths
basePath: /api/2.0
#
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
tags:
  - name: "/api/2.0"
    description: RackHD 2.0 Southbound API
paths:
  /tasks/bootstrap.js:
    x-swagger-router-controller: tasks
    get:
#      disable for now until we are using redfish renderer
#      x-swagger-template: 'bootstrap.js'
      operationId: getBootstrap
      summary: |
        get tasks bootstrap.js
      description: |
        used internally by the system - get tasks bootstrap.js
      parameters:
        - name: macAddress
          in: query
          description: query object to pass through to waterline.
          required: false
          type: string
      tags: [ "/api/2.0" ]
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/VersionsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /tasks/{identifier}:
    x-swagger-router-controller: tasks
    get:
    #do I need a serializer?
      operationId: getTasksById
      summary: |
        get specific task
      description: |
        get specific task
      parameters:
        - name: identifier
          in: path
          description: |
            task identifier
          required: true
          type: string
      tags: [ "/api/2.0" ]
      responses:
        200:
          description: |
            single task
          schema:
            type: object
        404:
          description: |
            There is no task with specified identifier.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
#do I need a serializer      x-swagger-serializer: pollers
      operationId: postTaskById
      summary: |
        post specific task
      description: |
        post specific task
      parameters:
        - name: identifier
          in: path
          description: |
            poller identifier
          required: true
          type: string
        - name: body
          in: body
          description: |
            obm settings to apply.
          required: true
          schema:
            $ref: '#/definitions/generic_obj'
      tags: [ "/api/2.0" ]
      responses:
        200:
          description: |
            Specifics of the specified task
          schema:
            type: object
        404:
          description: |
            There is no  task with specified identifier.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /notification:
    x-swagger-router-controller: notification
    post:
      operationId: notificationPost
      summary: |
        post a notification
      description: |
        post a notification
      parameters:
        - name: nodeId
          in: query
          description: |
            Node instance identifier
          required: false
          type: string
        - name: data
          in: body
          description: |
            notification data
          required: false
          schema:
            $ref: '#/definitions/notification_obj'
      tags: [ "/api/2.0" ]
      responses:
        201:
          description: |
            Specifics of the notification
          schema:
            type: object
        400:
          description: |
            bad request parameter passed or no active task or taskgraph.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /notification/progress:
    x-swagger-router-controller: notification
# In some environment (such as ipxe), the avaiable http client doesn't support POST, so we have
# to compromise to define below GET api to update progress information, but actually it does the
# job of verb "POST"
    get:
      operationId: notificationProgressPost
      summary: |
        Send progress notification to task
      description: |
        This API is used to update the progress information for a task instance
      parameters:
        - name: taskId
          in: query
          description: |
            The identifier of task instance which the progress applies to
          required: false
          type: string
        - name: maximum
          in: query
          description: |
            The maximum progress value
          required: false
          type: string
        - name: value
          in: query
          description: |
            The current progress value
          required: false
          type: string
      tags: [ "/api/2.0" ]
      responses:
        201:
          description: |
            Specifics of the notification
          schema:
            type: object
        400:
          description: |
            bad request parameter passed or no active task or taskgraph.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      operationId: notificationProgressPost
      summary: |
        Send progress notification to task
      description: |
        This API is used to update the progress information for a task instance
      parameters:
        - name: taskId
          in: query
          description: |
            The identifier of task instance which the progress applies to
          required: false
          type: string
        - name: maximum
          in: query
          description: |
            The maximum progress value
          required: false
          type: string
        - name: value
          in: query
          description: |
            The current progress value
          required: false
          type: string
      tags: [ "/api/2.0" ]
      responses:
        201:
          description: |
            Specifics of the notification
          schema:
            type: object
        400:
          description: |
            bad request parameter passed or no active task or taskgraph.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /wsmanCallback/{identifier}:
    x-swagger-router-controller: callback
    post:
      consumes:
      - application/json
      description: Receives callback from wsman based microservices.
      operationId: callbackPost
      parameters:
      - description: identifier
        in: path
        name: identifier
        required: true
        type: string
      - description: data
        in: body
        name: body
        required: true
        schema:
          type: object
      responses:
        201:
          description: Received data from service
          schema:
            $ref: '#/definitions/VersionsResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      summary: Async microservice response
      tags:
      - /api/2.0
  /swagger:
    x-swagger-pipe: swagger_raw
  /profiles:
      get:
        description: >
          Get the list of currently defined profiles. Profiles are scripts
          used by RackHD to control how a node PXE boots.
        operationId: profilesGet
        parameters:
        - collectionFormat: multi
          description: List of valid MAC addresses to lookup
          in: query
          items:
            type: string
          name: macs
          required: false
          type: array
        - collectionFormat: multi
          description: List of IP addresses to lookup
          in: query
          items:
            type: string
          name: ips
          required: false
          type: array
        - description:
            When macs parameter is not passed, passed with IP adds MAC address to lookup
          in: query
          name: mac
          required: false
          type: string
        - description:
            When macs parameters is not passed, passed with MAC adds IP address to lookup
          in: query
          name: ip
          required: false
          type: string
        responses:
          200:
            description: Successfully retrieved a list of profiles for specified mac / ip
            schema:
              type: object
          default:
            description: Unexpected error
            schema:
              $ref: '#/definitions/Error'
        summary: Get list of profiles
        tags:
        - /api/2.0
        x-authentication-type:
        - jwt
        x-privileges:
        - Read
        - profilesRead
      x-swagger-router-controller: profiles
  /templates/{name}:
      get:
        description: Get the template with the specified name.
        operationId: templatesGetByName
        parameters:
        - description: The name of the template
          in: path
          name: name
          required: true
          type: string
        - description: The node identifier
          in: query
          name: nodeId
          required: false
          type: string
        - collectionFormat: multi
          description: List of valid MAC addresses to lookup
          in: query
          items:
            type: string
          name: macs
          required: false
          type: array
        responses:
          200:
            description: Successfuly retrieved the specified template
            schema:
              type: object
          404:
            description: The template with specified identifier was not found
            schema:
              $ref: '#/definitions/Error'
          default:
            description: Unexpected error
            schema:
              $ref: '#/definitions/Error'
        summary: Get the specified template
        tags:
        - /api/2.0
        x-authentication-type:
        - jwt
        x-privileges:
        - Read
        - templatesRead
      head:
        description: Get the template headers with the specified name. Only gets headers
          and returns no body.
        operationId: templatesHeadByName
        parameters:
        - description: The name of the template
          in: path
          name: name
          required: true
          type: string
        - description: The node identifier
          in: query
          name: nodeId
          required: false
          type: string
        - collectionFormat: multi
          description: List of valid MAC addresses to lookup
          in: query
          items:
            type: string
          name: macs
          required: false
          type: array
        responses:
          200:
            description: Successfuly retrieved the specified template headers
            schema:
              type: object
          404:
            description: The template with specified identifier was not found
            schema:
              $ref: '#/definitions/Error'
          default:
            description: Unexpected error
            schema:
              $ref: '#/definitions/Error'
        summary: Get headers of the specified template
        tags:
        - /api/2.0
        x-authentication-type:
        - jwt
        x-privileges:
        - Read
      x-swagger-router-controller: templates
  /files/{fileidentifier}:
    get:
      description: Get file based on uuid or file name.
      operationId: filesGet
      parameters:
      - description: The uuid or file name of a file as provided when you originally stored it
        in: path
        name: fileidentifier
        required: true
        type: string
      responses:
        200:
          description: Successfully retrieved specified file
          schema:
            type: file
        404:
          description: File not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Failed to serve file request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      summary: Get a file
      tags:
      - /api/2.0
      x-authentication-type:
      - jwt
      x-privileges:
      - Read
      - filesRead
    put:
      consumes:
      - application/octet-stream
      - application/x-www-form-urlencoded
      description: Put file based on its filename. Returns the uuid of the stored file.
      operationId: filesPut
      parameters:
      - description: The filename of the file you want to store
        in: path
        name: fileidentifier
        required: true
        type: string
      responses:
        201:
          description: Successfully stored file
          schema:
            type: string
        500:
          description: Failure serving file request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      summary: Put a file
      tags:
      - /api/2.0
      x-authentication-type:
      - jwt
      x-privileges:
      - Write
      - filesWrite
      x-view: file.2.0.json
    x-swagger-router-controller: files
  /files/{filename}/md5:
    get:
      description: Get md5sum based on file name.
      operationId: filesMd5Get
      parameters:
      - description: File name of a file as provided when you originally stored it
        in: path
        name: filename
        required: true
        type: string
      responses:
        200:
          description: Successfully retrieved the md5sum of the specified file
          schema:
            type: object
        404:
          description: File not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Failed to serve file request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      summary: Get md5sum of file
      tags:
      - /api/2.0
      x-authentication-type:
      - jwt
      x-privileges:
      - Read
      - filesRead
      x-view: files.md5.2.0.json
    x-swagger-router-controller: files
definitions:
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string

  VersionsResponse:
    required:
      - message
    properties:
      message:
        type: string

  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string

  notification_obj:
    properties:
      nodeId:
        type: string

  generic_obj:
   type: object