REST API Guide – OpenManage Essentials Dell Engineering Team July 2016 A Dell Best Practices
Revisions Date Description March 2014 Initial release September 2014 Additional features included with OpenManage Essentials version 2.0 September 2015 Revisions included with OpenManage Essentials version 2.1 July 2016 Additional features included with OpenManage Essentials version 2.2 THIS DOCUMENT IS FOR INFORMATIONAL PURPOSES ONLY, AND MAY CONTAIN TYPOGRAPHICAL ERRORS AND TECHNICAL INACCURACIES. THE CONTENT IS PROVIDED AS IS, WITHOUT EXPRESS OR IMPLIED WARRANTIES OF ANY KIND. © 2016 Dell Inc.
Table of contents Revisions ..................................................................................................................................................................................................2 Introduction ............................................................................................................................................................................................5 1 Key Integration Concepts .........................................................
2.3.11 All Inventory ....................................................................................................................................................................... 30 2.4 Table Inventory .................................................................................................................................................................. 31 2.5 Device Group Hierarchy ........................................................................................................
Introduction This document provides a guide for integrating with OpenManage Essentials using Representational State Transfer (REST) APIs. It provides examples of using REST to perform common tasks based on integration use cases with other products such as OpenManage Mobile, Repository Manager, and the Dell Software group portfolio. This document is not intended to be an introduction to REST.
1 Key Integration Concepts This section covers key integration concepts that are applicable to all of the use cases that are addressed in the next section. 1.1 Client Integration Overview The REST client makes standard HTTP(S) requests to the REST API end-point. Each request is sent using a HTTP verb (for example, PUT, GET, POST, DELETE, HEAD, and OPTIONS) and includes a message body in XML format. The response uses a standard HTTP status code.
1.3 Security The REST services will *only* be exposed through HTTPS to ensure that the common threats associated with HTTP traffic are mitigated. The administrator will have the option of updating the SSL self-signed certificate with a customer-provided certificate (for example, by uploading a PKCS-12 certificate or by signing an application-generated CSR request). 1.4 Authentication Mechanisms There are several common schemes for enabling authentication of REST requests.
1.6 Resource Operations The standard HTTP methods are used for performing create, retrieve, update, and delete operations on resources. The mapping of the HTTP methods to operational semantics is described in the following table. 8 HTTP method Description Example GET Used to retrieve the resource representation. This method does not modify the resource across repeated invocations. The query parameters are appended to the URI to appropriately filter the resource instances.
1.7 Security Considerations The OpenManage Essentials REST PUT and DELETE operations require that the user IDs used to execute these commands have write access to the base directory where the OpenManage Essentials REST services are installed. If the write permission on this directory is not enabled for the user IDs used to access the DELETE and PUT operations, an “Unauthorized” error will be returned.
1.10 Request Headers The request header represents headers in the client HTTPS request that are used to communicate client preferences to the service end-point. The service will indicate the supported preference in the response header. The following table includes a few examples of request headers. For an extensive list of request headers, see List of HTTP header fields. 1.11 Request Header Description Example Accept Format of the data that is requested by the client.
1.12 Authorization 401 – Authorization failure Permission denied 403 – Permission denied Not found 404 – Resource not found Invalid request method 405 – Invalid request method Internal server error 500 – Internal server error Service unavailable 503 – Service unavailable Response Headers The following table includes a few examples of response headers. For an extensive list of response headers, see List of HTTP header fields.
2 OpenManage Essentials-Specific Resource Model The following sub-sections represent a subset of the use cases that OpenManage Essentials supports. The REST API support and the operation support will be incrementally refined based on consumer feedback over multiple OpenManage Essentials releases. Also, see the data filtering/sorting and pagination sections for patterns that can be used for performing paged retrieval of large result sets in OpenManage Essentials (for example, alerts, devices, and so on).
The following resource URI can be used to retrieve the child groups of a specific group: /DeviceGroups//ChildGroups The following resource URIs can be used to retrieve the devices associated with a specific group: /DeviceGroups//ChildDevices (to retrieve all the immediate child devices) /DeviceGroups//Devices (to retrieve all the leaf devices for the group by performing a recursive traversal of the hierarchy rooted at the group identified by ) The following res
Rollup Health Enumeration The rollup health enumeration values are defined in the following table. Enum Value Description 0 None – Health status is not available. 2 Unknown – Health status is unknown. 4 Normal – Health status is normal. 8 Warning – Health status is warning. 16 Critical – Health status is critical. Device Group Type Enumeration The device group type enumeration values are defined in the following table.
2.2 Devices The URI for accessing devices in OpenManage Essentials could be either based on the parent group resource or by directly accessing the devices.
DiscoveryTime The time when the device was last discovered. InventoryTime The time when the device was last inventoried. StatusTime The time when the device was last statused. OSName The name of the installed operating system. OSRevision The version of the operating system. NICS A collection of NIC elements identifying all the NICs associated with the particular device. IsIdrac True or false indicating whether the device instance is representing an iDRAC device.
19 UPS 20 Client 21 Powercserver 22 Compellent 23 NAS Appliance The type enumeration for the GlobalStatus is defined in the following table.
2.2.1 Devices By Direct Access :< BASE_URI>/Devices The resulting payload from this API is slightly different that the payload returned by the other devicerelated REST API calls. After all devices are enumerated in the resulting XML payload, two additional pieces of information are returned as well: AddedOrUpdatedTimestamp DeletedTimestamp Figure 1 Timestamps The AddedOrUpdatedTimestamp and DeletedTimestamp denote the latest timestamps associated with the device payload just returned.
For example, if the device listing was retrieved by an OpenManage Essentials REST consumer at time t1 and the consumer needs to get information about the devices that were added or modified or deleted at time t2 where t2 > t1, then the consumer, using the AddedOrUpdatedTimestamp and DeletedTimestamp obtained from the last call at t1, can get a list of only the changed and deleted devices using the following REST API: /Devices/{AddedOrUpdatedTimestamp}&{DeletedTimestamp} Figure 2 2.2.
Figure 3 Retrieving changed device information This particular REST API will typically be used by a consumer that does its own device management and tracking periodically based on a particular polling cycle. Instead of getting the whole list of devices to determine the changes, the consumer will be able to retrieve only the changed device information based on the timestamps obtained in a previous call. 2.
2.3.1 Firmware The following resource URI can be used to retrieve firmware information for a specific device identified by : //Firmware The attributes associated with each firmware instance are described in the following table. 2.3.2 Attribute Name Description Type The type of firmware. Name The name of the firmware. Version The version of the firmware.
2.3.3 NICs The following resource URI can be used to retrieve network interface information associated with a specific server identified by : //NIC The attributes associated with each NIC instance are described in the following table. 2.3.4 Attribute Name Description IPAddress The IP address of the NIC. MACAddress The MAC address of the NIC. Manufacturer The manufacturer of the NIC. Pingable A numeric indicator for whether the device can be pinged or not.
2.3.5 Memory The following resource URI can be used to retrieve memory information associated with a specific device with identified by : //Memory The attributes associated with each DIMM instance are described in the following table. Attribute Name Description Size The size of the DIMM in MB. Type The type of the DIMM. Name The name associated with the DIMM. Manufacturer The manufacturer of the DIMM. PartNumber The part number of the DIMM.
Figure 4 24 Total memory REST API Guide – OpenManage Essentials | Revision A02
2.3.6 Software Inventory The following resource URI can be used to retrieve software inventory information associated with a specific device identified by : //Software The attributes associated with each software entity instance are described in the following table. Attribute Name Description Description The description of the software entity. Version The version of the software entity. Type The type of the software entity.
2.3.7 Agent Information The following resource URI can be used to retrieve agent information associated with a specific device identified by : //Agents The attributes associated with the agent information are described in the following table. Attribute Name Description Name The name of the agent. Description The description of the agent. Version The version of the agent. Status The latest status reported by the agent. URL The management URL of the agent.
The values for the status reported by the agent are defined in the following table. 2.3.8 Agent Status Description 0 None – The status information is not available. 2 Unknown – The status is unknown. 4 Normal – The status is normal. 8 Warning – Warning status reported by the agent. 16 Critical – Critical status reported by the agent.
The device capability values are defined in the following table.
2.3.10 Warranty Information The following resource URI can be used to retrieve the warranty information of a device identified by : //Warranty Operations Supported: GET The warranty information is defined in the following table.
The following is an example for service tag 1234567: Figure 6 2.3.11 Warranty information All Inventory The following resource URI can be used to retrieve the entire inventory associated with a specific device identified by : //Inventory This URI would effectively return a concatenation of the individual components listed earlier (Firmware, Processor, NICs, Operating Systems, Memory, Software Inventory, Agents, ContactInfo, and DeviceCapabilities).
In addition to the components specified above, this command will return the following additional information: Enclosures There may be one or more enclosure entries. Each entry specifies the following attributes: Attribute Name Description EnclosureProductId The enclosure product ID. EnclosureServiceTag The Service Tag of the enclosure. EnclosureId The enclosure ID. SwitchInfos There may be one or more SwitchInfo entries. This section is applicable to switch devices only.
5 ContactInfo 6 Controller 7 CostOfOwnership 8 DeviceCard 9 Enclosure 10 EnclosureManagementModule 11 Firmware 12 FruInformation 13 HyperVGuestNICView 14 HyperVHostGuestView 15 MaserInfo 16 MemoryDevice 17 ModularChassisAssociation 18 NIC 19 OperatingSystem 20 PDUDeviceProperty 21 PowerSupply 22 PrinterCover 23 PrinterInputTray 24 PrinterOutputTray 25 PrinterSupply 26 Processor 27 RACDevice 28 SoftwareInventory 29 StorageBattery 30 StorageGroup 31 Swi
2.
The attributes associated with the returned payload are described in the following table. Attribute Name Description HierarchyAddedOrUpdatedTimestamp The last timestamp for the device group to device group hierarchy where an addition or update was performed. HierarchyDeletedTimestamp The last timestamp for the device group to device group hierarchy timestamp where a deletion was performed.
The attributes associated with the individual entries of the DeviceGroupToDeviceGroup section of the returned payload are described in the following table. Attribute Name Description Id The identifier of the relationship. DeviceGroupId The device group identifier of the child device group. ParentDeviceGroupId The device group identifier of the parent device group.
2.6 Device Logs The following resource URI can be used to retrieve the device logs: < DEVICE_BASE_URI>//HWLogs/SEL (to retrieve the SEL logs) OpenManage Essentials may expose Lifecycle Controller logs in the future and that would require a separate URI construct as the attributes exposed are slightly different (for example, recommended action and detailed description). Operations supported: GET The attributes associated with each log entry are represented in the following table. 2.
The attributes associated with an alert filter are described in the following table. Attribute Name Description Id The unique identifier for the filter. Name The name of the filter. Type The type of filter (for example, view filter, action filter, and so on). IsEnabled A flag indicating whether the filter is enabled or disabled. IsReadOnly A flag indicating whether the filter is read-only or editable.
Operations supported: GET, DELETE, and PUT Attributes (filtering): Id, Severity, and Status Attributes (sorting): Time Desc (by default) The attributes associated with the alerts are described in the following table. 38 Attribute Name Description Id The unique identifier for the alert. Severity The enumerated severity of the alert. Status The status of the alert (for example, to indicate whether the alert is acknowledged or not). Time The date/time for the alert.
ServiceTag The Service Tag of the device that initiated the alert IsIdrac ‘True’ or ‘False’. It signifies whether the device that generated the alert is an iDRAC device. The enumerated values for the Severity field are described in the following table. 2.8.
The response will be in the following format: false -2342839 Invalid operation on -2342839 72933 Event 72933 does not exist If the requested action for all of the alerts in the list are successfull, the return value will be true. No other information will be in the response.
2.9 Alert Subscriptions Alert subscriptions provide an option to register or subscribe for alerts that match a filter. The subscription mechanism will allow notifications of alerts to external subscribers. The following URI can be used to perform alert subscription operations: Alert subscriptions: /AlertSubscriptions Operations supported: GET, POST, PUT, and DELETE Attributes (filtering): Id The attributes associated with the alert subscription is described below.
2.9.2 AlertSubscription DELETE command Deletion of the subscription (or unsubscribe) is accomplished using the standard HTTP DELETE operation. Note: For the DELETE operation, you have to provide the DeviceId value to the alert subscription that you want to delete. 2.9.3 AlertSubscription POST example Data The payload for the POST command is an XML structure that defines the various fields that are needed to create an Alert Subscription. Note: All the values in the payload are case sensitive.
Figure 7 Alert subscription Figure 8 Error REST API Guide – OpenManage Essentials | Revision A02
2.9.4 AlertSubscription PUT command An update of the subscription information can be accomplished with a PUT operation. Note: The payload for the PUT operation is identical to the payload of the POST operation. Note: The subscription corresponding to the device identifier will be updated (if it exists). If the subscription with the corresponding device identifier does not exist, then the operation will return an error in the response header 2.
2.12 Tasks The following URI can be used to create a new task: Task URI :< BASE_URI>/Tasks Operations supported: GET and POST Attributes (filtering): TaskId 2.12.1 Power Control Task Creation The power control task can be created using the following parameters. The following resource URI can be used to create a power control task: Power control task URI :< BASE_URI>/Tasks/PowerControl (POST operation) The attributes associated with the power control task are described in the following table.
2.12.2 Task Start Time Consideration If the schedule field is set as part of the payload, then particular attention needs to be paid to the repeating time field of the schedule. For example, if the schedule is specified as 46 22 */1 * * *, it would translate as follows: 46: minute 22: hour */1: day of month *: weekly *: monthly *: yearly Therefore, the example translates to executing the task every day at 22:46 UTC.
A sample XML that would comprise the payload when initiating a POST operation to create a power control task is as follows: 0 A - Power Off - REST 3 Power Off Task 46 22 */1 * * * 1 1 2 3 4 Administrator Dell1234 1 2.12.
The values of the TaskState are defined in the following table. Value Description 1 Pending 2 Running 3 Stopped 4 Complete 5 Failed 6 Scheduled 7 Not Scheduled The details for task execution on multiple devices can be queried by /ExecutionDetails The attributes associated with task execution on multiple devices are described in the following table. 48 Attribute Name Description StartTime The start time of the task for the specific device.
The device Status enumeration is defined in the following table. 2.13 Value Description 0 In progress 1 Pending 2 Running 4 Complete 8 Warning 16 Failed 32 Stopped Application Information The following resource URI can be used to access information about the OME application: /Application Operations supported: GET The attributes associated with the application information are described in the following table. 2.14 Attribute Name Description Name The name of the application.
Attribute Name Description UserName The name of the currently authenticated user UserType The type of the user The type of user is defined in the following table. 2.
2.16.1 Report Types The following resource URI can be used for accessing a list of currently available reports: /Reports Operations supported: GET The types of reports are defined in the following table.
25 VirtualDiskInformation 26 WarrantyInformation 27 BiosConfiguration 28 IDracNetworkConfiguration 29 DeviceConfigurationCompliance 30 TemplateAssociation 31 AssignedIdentities 32 AllIdentityAttributes 33 AgentHealthStatus The format of the XML output with the report types is as follows: 52 REST API Guide – OpenManage Essentials | Revision A02
Figure 9 Report types Note: As new reports are added to OpenManage Essentials, they will be added to the list of report types. Using the /Reports operation provides the current list of supported reports. 2.16.
Report Types section. 2.16.3 Generic Report Format The following is an example of a generic report: Figure 10 Generic report The title of the report is the same as the report in OpenManage Essentials. The TotalRowCount is the number of rows in the entire report. If paginiation has been used as described in Data Pagination, then the RowOffset will be the number of rows skipped and the CurrentRowCount will be the number of rows included in this part of the report that has been returned.
The next part of the report are the column headers. The column number indicates the order of the columns. They match the names in the report, except for DeviceId. Device Id is included for convicence in retrieving data from other API calls. The data rows are a list of rows which include the cell data and the matching column number. There are no row numbers to indicate the order, rather it is the order in which the report is read.
A 56 Glossary Term Meaning REST Representational State Transfer RO Resource Oriented ROA Resource Oriented Architecture OME OpenManage Essentials OMM OpenManage Mobile REST API Guide – OpenManage Essentials | Revision A02
