API Reference¶
The examples below assume OpenDCRE is running on a given <ipaddress> and <port>. The default port for OpenDCRE is TCP port 5000. Currently, all commands are GET requests; a future version will expose these commands via POST as well.
Note
In the API reference information below, there are many references to board_id
and device_id
parameters.
For IPMI Devices, the values in a board’s hostnames
and ip_addresses
fields (e.g. from a
scan) can be used in place of the board_id
. Additionally, the device_info
field
for a given device, where specified, can be used in place of its device_id
.
As an example, a device read for a system temperature device on a board whose (abridged) scan information provides us with:
{
"board_id": "40000039",
"devices": [
{
"device_id": "0011",
"device_info": "System Temp",
"device_type": "temperature"
}
],
"hostnames": [
"kafka001.vapor.io"
],
"ip_addresses": [
"192.168.1.10"
]
}
We could formulate a temperature read call in a variety of ways:
GET /opendcre/1.3/read/temperature/rack_9/40000039/0011
GET /opendcre/1.3/read/temperature/rack_9/40000039/System%20Temp
GET /opendcre/1.3/read/temperature/rack_9/kafka001.vapor.io/0011
GET /opendcre/1.3/read/temperature/rack_9/kafka001.vapor.io/System%20Temp
GET /opendcre/1.3/read/temperature/rack_9/192.168.1.10/0011
GET /opendcre/1.3/read/temperature/rack_9/192.168.1.10/System%20Temp
As of version 1.3.0, this only works for IPMI Devices, but this functionality will come later for all other devices.
asset information¶
Get asset information for a given device. The device’s device_type
must be of type system
(as reported by
the scan command). Asset information can consist of board information, chassis information,
and product information.
Request¶
Format¶
GET /opendcre/<version>/asset/<rack_id>/<board_id>/<device_id>
Parameters¶
rack_id: | The id of the rack on which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
board_id reserved for future use in OpenDCRE. IPMI Bridge board has a special board_id of 40NNNNNN,
where NNNNNN corresponds to the hex string id of each configured BMC. For IPMI, the board_id can also be
a hostname/ip_address that is associated with the given board. |
device_id: | The device to read asset information for on the specified board. Hexadecimal string representation of
a 2-byte integer value - range 0000..FFFF. Must be a valid, existing device, where the device_type known
to OpenDCRE is of type system - else, a 500 error is returned. For IPMI, the device_id can also be the
value of the device_info field associated with the given device, if present. |
Example¶
http://opendcre:5000/opendcre/1.3/asset/00000001/0004
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-asset-information",
"title": "OpenDCRE Asset Information",
"type": "object",
"properties": {
"bmc_ip": {
"type": "string"
},
"board_info": {
"type": "object",
"properties": {
"manufacturer": {
"type": "string"
},
"part_number": {
"type": "string"
},
"product_name": {
"type": "string"
},
"serial_number": {
"type": "string"
}
}
},
"chassis_info": {
"type": "object",
"properties": {
"chassis_type": {
"type": "string"
},
"part_number": {
"type": "string"
},
"serial_number": {
"type": "string"
}
}
},
"product_info": {
"type": "object",
"properties": {
"asset_tag": {
"type": "string"
},
"manufacturer": {
"type": "string"
},
"part_number": {
"type": "string"
},
"product_name": {
"type": "string"
},
"serial_number": {
"type": "string"
},
"version": {
"type": "string"
}
}
}
}
}
Note
Note that the bmc_ip
field is only present for IPMI device asset info.
Example¶
{
"bmc_ip": "192.168.1.118",
"board_info": {
"manufacturer": "Quanta",
"part_number": "0001",
"product_name": "Winterfell",
"serial_number": "S1234567"
},
"chassis_info": {
"chassis_type": "rack mount chassis",
"part_number": "P1234567",
"serial_number": "S1234567"
},
"product_info": {
"asset_tag": "A1234567",
"manufacturer": "Quanta",
"part_number": "P1234567",
"product_name": "Winterfell",
"serial_number": "S1234567",
"version": "v1.2.0"
}
}
Errors¶
500: |
|
---|
boot target¶
The boot target command may be used to get or set the boot target for a given device (whose device_type must be
system
). The boot_target command takes two required parameters - board_id
and device_id
, to identify
the device to direct the boot_target command to. Additionally, a third, optional parameter, target
may be used
to set the boot target.
Request¶
Format¶
GET /opendcre/<version>/boot_target/<rack_id>/<board_id>/<device_id>[/<target>]
Parameters¶
rack_id: | The id of the rack upon which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
|
device_id: | The device to issue boot target command to on the specified board. Hexadecimal string representation of
2-byte integer value - range 0000..FFFF. Must be a valid, existing device, where the |
target: | (optional) Valid target for the boot_target command include:
|
If a target is not specified, boot_target makes no changes, and simply retrieves and returns the system boot target.
If target
is specified and valid, the boot_target command will return the updated boot target value, as provided
by the remote device.
Example¶
http://opendcre:5000/opendcre/1.3/boot_target/00000001/0004
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-boot-target",
"title": "OpenDCRE Boot Target",
"type": "object",
"properties": {
"target": {
"type": "string",
"enum": [
"no_override",
"hdd",
"pxe"
]
}
}
}
Example¶
{
"target": "no_override"
}
Errors¶
500: |
|
---|
fan¶
The fan control command is used to get the fan speed (in RPM) for a given fan.
Request¶
Format¶
GET /opendcre/<version>/fan/<rack_id>/<board_id>/<device_id>[/<speed_rpm>]
Parameters¶
rack_id: | The id of the rack upon which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
|
device_id: | The device to issue fan control command to on the specified board. Hexadecimal string representation of
2-byte integer value - range 0000..FFFF. Must be a valid, existing device, where the |
speed_rpm: | (optional) Numeric decimal value to set fan speed to, in range of 0-10000. Note IPMI devices do not yet support the setting of fan speed, so this parameter can be ignored for all IPMI setups. |
Example¶
http://opendcre:5000/opendcre/1.3/fan/00000001/0002
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-fan-speed",
"title": "OpenDCRE Fan Speed",
"type": "object",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"speed_rpm": {
"type": "number"
}
}
}
Example¶
{
"health": "ok",
"speed_rpm": 4100.0,
"states": []
}
Errors¶
500: |
|
---|
host information¶
Get the hostname(s) and IP address(es) for a given host. The device’s device_type
should be of type system
(as reported by the scan command).
Request¶
Format¶
GET /opendcre/<version>/host_info/<rack_id>/<board_id>/<device_id>
Parameters¶
rack_id: | The id of the rack upon which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
board_id reserved for future use in OpenDCRE. IPMI Bridge board has a special board_id of 40NNNNNN, where
NNNNNN corresponds to the hex string id of each configured BMC. For IPMI, the board_id can also be
a hostname/ip_address that is associated with the given board. |
device_id: | The device to issue host info control command to on the specified board. Hexadecimal string representation of
2-byte integer value - range 0000..FFFF. Must be a valid, existing device, where the device_type known to
OpenDCRE is system - else, a 500 error is returned. For IPMI, the device_id can also be the
value of the device_info field associated with the given device, if present. |
Example¶
http://opendcre:5000/opendcre/1.3/host_info/00000001/0001
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-host-information",
"title": "OpenDCRE Host Information",
"type": "object",
"properties": {
"hostnames": {
"type": "array",
"items": {
"type": "string"
}
},
"ip_addresses": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
Example¶
{
"hostnames": [
"cassandra000"
],
"ip_addresses": [
"10.10.1.16"
]
}
Errors¶
500: |
|
---|
LED¶
The LED control command is used to get and set the chassis “identify” LED state. led
devices known to OpenDCRE
allow LED state to be set and retrieved.
Request¶
Format¶
GET /opendcre/<version>/led/<rack_id>/<board_id>/<device_id>[/<led_state>]
Parameters¶
rack_id: | The id of the rack upon which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
|
device_id: | The device to issue LED control command to on the specified board. Hexadecimal string representation of
2-byte integer value - range 0000..FFFF. Must be a valid, existing device, where the |
led_state: | (optional) The LED state to set. Valid values include:
|
Example¶
http://opendcre:5000/opendcre/1.3/led/00000001/0005
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-led-control",
"title": "OpenDCRE LED Control",
"type": "object",
"properties": {
"led_state": {
"type": "string",
"enum": [
"on",
"off"
]
}
}
}
Example¶
{
"led_state": "on"
}
Errors¶
500: |
|
---|
location¶
The location command returns the physical location of a given board in the rack, if known, and may also include
a given device’s position within a chassis (when the device_id
parameter is specified). IPMI boards return
unknown
for all fields of physical_location
as location information is not provided by IPMI.
Request¶
Format¶
GET /opendcre/<version>/location/<rack_id>/<board_id>[/<device_id>]
Parameters¶
rack_id: | The id of the rack upon which the specified board and device reside. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
board_id reserved for future use in OpenDCRE. IPMI Bridge board has a special board_id of 40NNNNNN,
where NNNNNN corresponds to the hex string id of each configured BMC. For IPMI, the board_id can also be
a hostname/ip_address that is associated with the given board. |
device_id: | (optional) The device to get location for on the specified board. Hexadecimal string representation of
2-byte integer value - range 0000..FFFF. Must be a valid, existing device known to OpenDCRE - else, a 500
error is returned. For IPMI, the device_id can also be the value of the device_info field associated
with the given device, if present. |
Response¶
Schema¶
Device Location¶
{ "$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-device-location", "title": "OpenDCRE Device Location", "type": "object", "properties": { "chassis_location": { "type": "object", "properties": { "depth": { "type": "string", "enum": [ "unknown", "front", "middle", "rear" ] }, "horiz_pos": { "type": "string", "enum": [ "unknown", "left", "middle", "right" ] }, "vert_pos": { "type": "string", "enum": [ "unknown", "top", "middle", "bottom" ] }, "server_node": { "type": "string" } } }, "physical_location": { "type": "object", "properties": { "depth": { "type": "string", "enum": [ "unknown", "front", "middle", "rear" ] }, "horizontal": { "type": "string", "enum": [ "unknown", "left", "middle", "right" ] }, "vertical": { "type": "string", "enum": [ "unknown", "top", "middle", "bottom" ] } } } } }
Board Location¶
{ "$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-board-location", "title": "OpenDCRE BoardLocation", "type": "object", "properties": { "physical_location": { "type": "object", "properties": { "depth": { "type": "string", "enum": [ "unknown", "front", "middle", "rear" ] }, "horizontal": { "type": "string", "enum": [ "unknown", "left", "middle", "right" ] }, "vertical": { "type": "string", "enum": [ "unknown", "top", "middle", "bottom" ] } } } } }
Example¶
Device Location¶
{ "chassis_location": { "depth": "unknown", "horiz_pos": "unknown", "server_node": "unknown", "vert_pos": "unknown" }, "physical_location": { "depth": "unknown", "horizontal": "unknown", "vertical": "unknown" } }
Board Location¶
{ "physical_location": { "depth": "unknown", "horizontal": "unknown", "vertical": "unknown" } }
power¶
Control device power, and/or retrieve its power supply status. The specified device’s device_type
must be of
type power
(as reported by the scan command).
Request¶
Format¶
GET /opendcre/<version>/power/<rack_id>/<board_id>/<device_id>[/<command>]
Parameters¶
rack_id: | The id of the rack which the specified board and device reside on. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
|
device_id: | The device to issue power command to on the specified board. Hexadecimal string representation of 2-byte
integer value - range 0000..FFFF. Must be a valid, existing device, where the |
command: | (optional) The power command to issue. Valid commands are:
|
For all commands, power status is returned as the command’s response.
Example¶
http://opendcre:5000/opendcre/1.3/power/00000001/000d/on
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-power-status",
"title": "OpenDCRE Power Status",
"type": "object",
"properties": {
"input_power": {
"type": "number"
},
"input_voltage": {
"type": "number"
},
"output_current": {
"type": "number"
},
"over_current": {
"type": "boolean"
},
"pmbus_raw": {
"type": "string"
},
"power_ok": {
"type": "boolean"
},
"power_status": {
"type": "string",
"enum": [
"on",
"off"
]
},
"under_voltage": {
"type": "boolean"
}
}
}
Example¶
{
"input_power": 198.57686579513486,
"input_voltage": 12.500651075576853,
"output_current": 15.879801734820322,
"over_current": false,
"pmbus_raw": "0,12000,2400,3356",
"power_ok": true,
"power_status": "on",
"under_voltage": false
}
Errors¶
500: |
|
---|
read¶
Read a value from the given board_id
and device_id
for a specific device_type
. The specified
device_type
must match the actual physical device type (as reported by the scan command),
and is used to return a translated raw reading value (e.g. temperature in C for a thermistor) based on the existing
algorithm for a given sensor type.
Request¶
Format¶
GET /opendcre/<version>/read/<device_type>/<rack_id>/<board_id>/<device_id>
Parameters¶
device_type: | String value (lower-case) indicating what type of device to read: thermistor , temperature ,
humidity , led , fan_speed , pressure , voltage |
---|---|
rack_id: | The id of the rack which the board and device reside on. |
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
board_id reserved for future use in OpenDCRE. IPMI Bridge board has a special board_id of 40NNNNNN
(where NNNNNN is the hex string id of each individual BMC configured with the IPMI Bridge). For IPMI, the
board_id can also be a hostname/ip_address that is associated with the given board. |
device_id: | The device to read on the specified board. Hexadecimal string representation of a 2-byte integer
value - range 0000..FFFF. Must be a valid, existing device, where the device_type known to OpenDCRE matches
the device_type specified in the command for the given device - else, a 500 error is returned. For IPMI, the
device_id can also be the value of the device_info field associated with the given device, if present. |
Example¶
http://opendcre:5000/opendcre/1.3/read/thermistor/00000001/0001
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-sensor-reading",
"title": "OpenDCRE Sensor Reading",
"type": "object",
"oneOf": [
{
"description": "Temperature Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"temperature_c": {
"type": "number"
}
}
},
{
"description": "Thermistor Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"temperature_c": {
"type": "number"
}
}
},
{
"description": "Fan Speed Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"speed_rpm": {
"type": "number"
}
}
},
{
"description": "LED Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"led_state": {
"type": "string",
"enum": [
"on",
"off"
]
}
}
},
{
"description": "Pressure Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"pressure_kpa": {
"type": "number"
}
}
},
{
"description": "Voltage Readings",
"properties": {
"health": {
"type": "string"
},
"states": {
"type": "array"
},
"voltage": {
"type": "number"
}
}
}
]
}
Example¶
{
"health": "ok",
"states": [],
"temperature_c": 19.73
}
Errors¶
500: |
|
---|
scan¶
The scan
command polls boards and devices attached to the board. There are primarily two ways that scan
operates – “scan all”, and “scan entity”, where an entity could be a rack or a board. When performing a
“scan all” command, if a scan cache does not exist, it will scan the physical boards and devices. If a scan
cache does exist, it will use the results from the cache. To refresh the scan cache, the “force scan” command
should be used.
Note
It is likely a good idea for applications to scan for all boards on startup, to ensure a proper map of boards and devices is available to the application. Mismatches of board and device types and identifiers will result in 500 errors being returned for various commands that rely on these values mapping to actual hardware.
Request¶
Format¶
scan all: | GET /opendcre/<version>/scan
|
---|---|
force scan: | GET /opendcre/<version>/scan/force
|
scan rack: | GET /opendcre/<version>/<rack_id>
|
scan board: | GET /opendcre/<version>/<rack_id></board_id>
|
Parameters¶
force: | (optional) A flag which, when present, will force the re-scan of all racks, boards, and devices. This parameter is only associated with “scan all” behavior and does not apply to scans at a rack or board level. Forcing a scan re-scans the devices and updates the scan cache. |
---|---|
rack_id: | (optional) The id of the rack to scan, if only the rack is specified. If the rack is specified with a board id, this is the rack where the target board resides. |
board_id: | (optional) Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper
byte of board_id reserved for future use in OpenDCRE. IPMI Bridge boards have a special board_id of
40NNNNNN (where NNNNNN is the hex string id of each configured BMC). For IPMI, the board_id can also be
a hostname/ip_address that is associated with the given board. |
Example¶
GET http://opendcre:5000/opendcre/1.3/scan
GET http://opendcre:5000/opendcre/1.3/scan/force
GET http://opendcre:5000/opendcre/1.3/scan/rack_1
GET http://opendcre:5000/opendcre/1.3/scan/rack_1/00000001
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-boards-devices",
"title": "OpenDCRE Boards and Devices",
"type": "object",
"properties": {
"racks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rack_id": {
"type": "string"
},
"boards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"board_id": {
"type": "string"
},
"devices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"device_id": {
"type": "string"
},
"device_type": {
"type": "string",
"enum": [
"temperature",
"thermistor",
"humidity",
"led",
"system",
"power",
"fan_speed",
"pressure",
"voltage",
"power_supply"
]
}
}
}
},
"hostnames": {
"type": "array",
"items": {
"type": "string"
}
},
"ip_addresses": {
"type": "array",
"items": {
"type": "string"
}
},
}
}
}
}
}
}
}
}
Example¶
{
"racks": [
{
"boards": [
{
"board_id": "00000001",
"devices": [
{
"device_id": "0001",
"device_type": "system"
},
{
"device_id": "0002",
"device_type": "fan_speed"
},
{
"device_id": "0003",
"device_type": "fan_speed"
},
{
"device_id": "0004",
"device_type": "power"
},
{
"device_id": "0005",
"device_type": "led"
},
{
"device_id": "2000",
"device_type": "temperature"
},
{
"device_id": "4000",
"device_type": "temperature"
}
],
"hostnames": [
"kafka001.vapor.io"
],
"ip_addresses": [
"192.168.1.10"
]
}
],
"rack_id": "rack_1"
}
]
}
service version¶
The OpenDCRE service version command identifies the version of OpenDCRE running on the OpenDCRE instance being queried. Since OpenDCRE’s REST API commands include the API version in the URI, this endpoint provides a means of getting that version if it is otherwise unknown.
test¶
The test command provides a way to verify that the OpenDCRE service is running. It has no dependencies on any of the configured devicebus interfaces, so it serves only to test that the service is up and reachable - not that it is configured correctly. The command takes no arguments and, if successful, returns a status message of “ok”.
version¶
Get version information about a board.
Request¶
Format¶
GET /opendcre/<version>/version/<rack_id>/<board_id>
Parameters¶
rack_id: | The rack id associated with the specified board. |
---|---|
board_id: | Hexadecimal string representation of 4-byte integer value - range 00000000..FFFFFFFF. Upper byte of
board_id reserved for future use in OpenDCRE. IPMI Bridge board has a special board_id of 40000000.
For IPMI, the board_id can also be a hostname/ip_address that is associated with the given board. |
Example¶
http://opendcre:5000/opendcre/1.3/version/00000001
Response¶
Schema¶
{
"$schema": "http://schemas.vapor.io/opendcre/v1.3/opendcre-1.3-version",
"title": "OpenDCRE Board Version",
"type": "object",
"properties": {
"api_version": {
"type": "string"
},
"firmware_version": {
"type": "string"
},
"opendcre_version": {
"type": "string"
}
}
}
Example¶
{
"api_version": "1.3",
"firmware_version": "OpenDCRE Emulator v1.3.0",
"opendcre_version": "1.3.0"
}