REST API Guide – OpenManage Essentials Dell OME Engineering Team Steve Heracleous Pritesh Prabhu Sudhir Shetty David Warden September 2014 A Dell Best Practices
Revisions Date Description March 2014 Initial release September 2014 Additional features included with OpenManage Essentials version 2.0 THIS WHITE PAPER 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. © 2014 Dell Inc. All rights reserved. Reproduction of this material in any manner whatsoever without the express written permission of Dell Inc. is strictly forbidden.
Table of contents Revisions ..................................................................................................................................................................................................2 Introduction ............................................................................................................................................................................................5 1 Key Integration Concepts .........................................................
2.4 Table Inventory ................................................................................................................................................................. 27 2.5 Device Group Hierarchy ................................................................................................................................................. 29 2.5.1 Retrieving Device Hierarchy Information That Has Changed .................................................................................
Introduction This document provides a guide for integrating with OpenManage Essentials (OME) 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 either JSON or 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. 1.7 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.
Typically, on a default installation, the REST services top level directory is as shown below in the screenshot. 1.8 Data Filtering And Sorting Data filtering can be accomplished by associating queries with the GET request. In the simplest form, it is a set of parameter name/value pairs that are appended to the request. The following is an example of data filtering: /Alerts?Severity=16&Status=1 (To get the list of critical acknowledged alerts 16: Critical Severity, 1: Status Acknowledged) 1.
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 OME- Specific Resource Model The following sub- sections represent a subset of the use cases that OME supports. The REST API support and the operation support will be incrementally refined based on consumer feedback over multiple OME 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 OME (for example, alerts, devices, and so on).
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 resource URI can be used to retrieve information about a specific group: This URI returns the group attrib
Device Group Type Enumeration The device group type enumeration values are defined in the following table. 2.2 Enum Value Description 0 Unknown 1 System 2 Factory 4 User (custom group) 8 Query 16 Pseudo 32 AppLaunch 64 Internal -1 AllGroups 128 Tasks Devices The URI for accessing devices in OME could be either based on the parent group resource or by directly accessing the devices.
Any of the URIs specified earlier will be referenced as the in the subsequent sections of this document. The attributes associated with each device are described in the following table. Attribute Name Description Id The unique identifier for the device. Type The type enumeration for the device. Name The name of the device. DNSName The DNS name of the device. GlobalStatus The global HW status of the device. PowerStatus The power status of the device.
6 Portable 7 NetPC 8 Switch 9 CMC 10 KVM 11 Printer 12 Tape 13 EMC 14 FCSWITCH 15 MDStorage 16 EqualLogic 17 Force10 18 PDU 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 The AddedOrUpdatedTimestamp and DeletedTimestamp denote the latest timestamps associated with the device payload just returned.
/Devices/{AddedOrUpdatedTimestamp}&{DeletedTimestamp} 2.2.2 Changed Device Information The changed device information can be obtained by the following REST API: /Devices/{AddedOrUpdatedTimestamp}&{DeletedTimestamp} The values of the AddedOrUpdatedTimestamp and DeletedTimestamp would have been obtained by a previous call to the /Devices REST API.
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.3 Device Inventory The URIs described in this section can be used to retrieve more detailed inventory for each device.
2.3.2 Attribute Name Description Type The type of firmware. Name The name of the firmware. Version The version of the firmware. Processor The following resource URI can be used to retrieve information about the CPUs associated with a specific server identified by : //Processor The attributes associated with each processor instance are described in the following table. 2.3.3 Attribute Name Description MaxSpeed The maximum speed of the processor.
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.
All DIMMS that are currently installed in the device will be returned. At the end of the envelope, the total memory installed will be returned. The following is an example of the returned XML payload: 2.3.
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. The software type is described in the following table. Type Description APAC 2.3.
Note: In the case of the OpenManage Server Administrator (OMSA) agent, the value of the URL is a concatenated list of various URLs separated by the comma ‘,’ character. The consumer of this API will have to tokenize this output and attempt a web connection to each of the URLs to determine which URL is responsive before surfacing the URL to the actual consumer. The following is an example of the URL for OMSA as returned in the REST XML payload.
The attributes associated with the contact information are described in the following table. 2.3.9 Attribute Name Description DeviceId The device identifier associated with the contact information. ContactName The name of the contact associated with the device. ContactInformation The information about the contact associated with the device. ContactDescription The description of the contact associated with the device.
2.3.
SwitchInfos There may be one or more SwitchInfo entries. This section is applicable to switch devices only. Each entry specifies the following attributes: 2.4 Attributes Description Index Indicates the number of units in the device. SerialNumber Hardware identifier. SwitchRole Indicates if the unit is a management unit, standby unit, stack unit, and local unit.
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 SwitchDevice 32 TapeDrive 33 TapeLibrary 34 TPMInfo 35 UPSPhysicalBattery 36 VirtualDisk 37 VirtualFlash 38 VMDeviceInfoView 39 VMHostInfo 40 EventCatalog 41 EventCategory 42 EventSource 43
2.5 44 HyperVGuestMemoryInfo 45 HyperVGuestNICInfo 46 HyperVHostInfo 47 DeviceGroup 48 DeviceGroupToDevice 49 NASApplianceNode 50 SoftwareInventoryOOB Device Group Hierarchy Some consumers of the OME REST API services will require the capability of retrieving information that has changed since a particular point in time. The OME server continuously updates its database with new device information, new hierarchical information, and information that has been deleted.
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) OME 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.
To retrieve alerts associated with a specific alert filter, the following resource URI can be used: The following URI enables filtering the alerts based on the criteria defined by the alert filter. /AlertFilters//Alerts To get a summary by severity for each alert filter, the following URI can be used: /AlertFilters//Summary The attributes associated with the alert filter are described in the following table. 2.
The attributes associated with the alerts are described in the following table. 34 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. Message The message corresponding to the alert. EventCategory The event category for the alert. EventSource The OME alert source name for the alert.
Deletion of the alert is accomplished using the standard HTTP DELETE operation. To acknowledge an alert, you can perform a PUT operation on the specific alert instance with an updated Status attribute. The PUT operation on any other attribute will return an error. The enumerated values for the Severity field are described in the following table. 2.8.
The attributes associated with the alert subscription is described below. Attribute Name Description Id The unique identifier for the subscription. IdSubscriberService The enumerated type or identifier of the subscription service. This enables association with the correct notification mechanism. UserName The user name of the subscriber. Description The description of the subscriber (for example, mobile device model). IsEnabled A flag indicating whether this subscription is enabled or disabled.
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.
REST API Guide – OpenManage Essentials | Revision A01
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.
Operations supported: GET and POST Attributes (filtering): TaskId 2.11.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. Attribute Name Description Id Always set this to 0 when creating a new task.
2.11.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.11.
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. 43 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.12 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.13 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.
A 46 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 A01
