static/monorail-2.0-sb.yaml
# Copyright 2015-2017 Dell Inc. or its subsidiaries. All Rights Reserved.
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
/ucsCallback:
x-swagger-router-controller: callback
post:
operationId: ucsCallbackPost
summary: |
Callback for UCS nodes
description: |
Callback for UCS nodes
parameters:
- name: callbackId
in: query
description: |
callback id to identify data belongings
required: true
type: string
tags: [ "/api/2.0" ]
responses:
200:
description: Data is accepted and sent
schema:
type: object
400:
description: |
bad request parameter passed
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/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