REST API Guide – OpenManage Essentials Dell OME Engineering Team Steve Heracleous Pritesh Prabhu Sudhir Shetty David Warden March 2014 A Dell Best Practices
Revisions Date Description March 2014 Initial release 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. For more information, contact Dell.
Table of contents Revisions ............................................................................................................................................................................................. 2 Introduction ....................................................................................................................................................................................... 5 1 Key Integration Concepts..................................................................
2.4.1 Retrieving Device Hierarchy Information That Has Changed ............................................................................... 27 2.6 Device Logs .................................................................................................................................................................... 28 2.7 Alert Filters .................................................................................................................................................................
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.
1.8 Data Pagination Data pagination can be accomplished by providing additional information in the GET request corresponding to a chunk of data. The response returns information on the total number of entries that could be used to reset any page numbering if the data has changed since the last call. /Alerts/$top=250 This query will return the first chunk of data corresponding to the top 250 records.
1.10 Response Codes For synchronous operations, the server returns HTTP response codes 200 or 204 depending on the request. For long- running operations, the server returns a status code of 202 along with a HTTP response header (Location), corresponding to the URI of the temporary resource that can be used to monitor the operation. The following table includes a few examples of response codes. For an extensive list of response codes, see List of HTTP status codes.
1.12 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. 11 Response Header Description Content- Type Specifies the format of the content that Content- Type: application/xml; is returned by the server. If there are charset=utf- 8 multiple formats that could be accepted in the client request (using the Accept header), the server chooses the appropriate supported format.
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.
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 Value Description 0 None 2 Unknown 4 Normal 8 Warning 16 Critical 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.
The AddedOrUpdatedTimestamp and DeletedTimestamp denote the latest timestamps associated with the device payload just returned. These timestamps can be used to retrieve delta information by a consumer.
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.
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.
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.6 Software Inventory The following resource URI can be used to retrieve software inventory information associated with a specific device identified by : //Software 21 REST API Guide – OpenManage Essentials | Version 1.
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.
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. 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.
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. 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.
2.9.3 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.4 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 | Version 1.
2.9.6 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.
2.12.5 Task Status And Progress Information =/Tasks/ The following resource URI can be used to query the task execution summary: /ExecutionSummary Operations supported: GET The attributes associated with the task status and progress information are described in the following table. Attribute Name Description StartTime The start time of the task. EndTime The end time of the task. TaskState The enumerated state of the task.
The attributes associated with task execution on multiple devices are described in the following table. Attribute Name Description StartTime The start time of the task for the specific device. EndTime The end time of the task for the specific device. Status The status enumeration of the task for this device. DeviceId The device identifier for the task. Summary The summary of the task execution for the specific device. Details The details of the task execution for the specific device.
The attributes associated with the application information are described in the following table. 2.14 Attribute Name Description Name The name of the application. Description Description of the application. Vendor The vendor of the application. Version The software version. Build Number The build number. URL The URL for the web- based management application. GUID A unique identifier for the OME instance.
A 41 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 | Version 1.
