Copyright © 2011 Raritan, Inc.
PIQAPI-0C-v3.0.0-E
May 2011
255-80-6102-00
Power IQ
WS-API Programming Guide Release 3.0
This document contains proprietary information that is protected by copyright. All rights reserved. No part of this document may be photocopied, reproduced, or translated into another language without express prior written consent of Raritan, Inc.
© Copyright 2011 Raritan, Inc. All third-party software and hardware mentioned in this document are registered trademarks or trademarks of and are the property of their respective holders.
FCC Information
This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference in a commercial installation. This equipment generates, uses, and can radiate radio frequency energy and if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. Operation of this equipment in a residential environment may cause harmful interference.
VCCI Information (Japan)
Raritan is not responsible for damage to this product resulting from accident, disaster, misuse, abuse, non-Raritan modification of the product, or other events outside of Raritan's reasonable control or not arising under normal operating conditions.
iii
Contents
Chapter 1 Introduction 5
Chapter 2 SOAP API 6
Use Cases ..................................................................................................................................... 7 Use case 1: Asset management system/data synchronization ........................................... 7 Use case 2: Power control ................................................................................................... 7
Functional Description ................................................................................................................... 7 Fields in Power IQ ............................................................................................................... 7 List of operations in the API ............................................................................................... 12
Technical description ................................................................................................................... 13 Getting started ................................................................................................................... 13 Security .............................................................................................................................. 14 Authorization ...................................................................................................................... 15 Synchronous and Asynchronous Method Calls ................................................................. 15 Internationalization............................................................................................................. 18
Power Control Examples ............................................................................................................. 19 Step 1: Current state of device .......................................................................................... 19 Step 2: Switch outlet off ..................................................................................................... 20 Step 3: Check status of job ................................................................................................ 21
FindEDMentities Examples .......................................................................................................... 22 Setting the Paging_Limit for EDM Queries ........................................................................ 22 Returning Multiple Entities Using the IN Predicate ............................................................ 23 Using the LIKE Predicate .................................................................................................. 24 Finding Exact Matches Using the EQUAL Predicate ........................................................ 25 Creating Queries With Multiple Conditions ........................................................................ 26
Appendix A References ............................................................................................................ 28
Chapter 3 REST API 29
Getting started ............................................................................................................................. 30 Enable the API ................................................................................................................... 30 Setup a Test Environment (RESTClient) ........................................................................... 31 Accept HTTPS Certificate .................................................................................................. 31
Authentication .............................................................................................................................. 34 Difference Between PUT and GET Requests ............................................................................. 34
Example: Changing the Light on an Asset Strip ................................................................ 35 Data Model ................................................................................................................................... 38
Overview of API calls ......................................................................................................... 38 PDUs ................................................................................................................................. 38 IT Devices .......................................................................................................................... 39 Asset Strips ........................................................................................................................ 39 Events ................................................................................................................................ 40
Contents
iv
Jobs ................................................................................................................................... 40 Miscellaneous .................................................................................................................... 40
Sorting and Filtering ..................................................................................................................... 41 Synchronous vs. Asynchronous .................................................................................................. 41 Frequently Asked Questions ........................................................................................................ 42
Why do I see "Error: could not connect to server" in the RESTclient? .............................. 42 Why do I get NoMethodError in my response? ................................................................. 43
Index 45
5
This section describes the Power IQ web services APIs. This API is bi-directional: external applications can access and update the information in Power IQ, and request power control actions.
In short, the document describes:
Example use cases of what can be done with this API
A technical description of the API
A functional description of the API including a list of API calls, and an overview of the relevant objects and their fields
The word "PDU" in this document means "rack PDU". The concept "EDM entity" includes PDUs, Devices, Racks, Data Centers etc. EDM is an abbreviation of Enterprise Data Model.
Power IQ can be used:
as a stand-alone application (without integration with an external application)
integrated with an external application using the API described in this document
a combination of both, because changes made in Power IQ will show up in the external asset management application and vice versa
Chapter 1 Introduction
6
This is a web services API that uses SOAP over HTTPS
Creating/updating/deleting Devices, PDU, Racks etc can be done through this interface (initiated by the Client application). See Functional Description (on page 7).
The SOAP API also supports Power Control. See Functional Description (on page 7).
The SOAP API uses WSDL and XML schema files to define the objects in the web services API. The WSDL will define data types, required fields, lengths of fields etc.
One cannot do firmware upgrade or bulk configuration of PDUs through the API
Administrative settings of Power IQ (such as its IP address, security settings etc) cannot be changed through the API. This includes user groups/role management.
Authentication is done using WS-Security. See Getting Started (on page 13).
Roles and permissions will be respected. This way, it is possible to define users on Power IQ that will be allowed to use the API, and fine grained permissions control will be available (the same permissions are available in the user interface).
Roles and permissions defined in Power IQ are also applicable to the Power IQ web services API. If a user is given permission to only control the power of one rack, that user will only be able to control the power of that one rack, whether through the Power IQ web interface, or using the Power IQ web services API. If the third-party application integrating with Power IQ needs less restrictive permissions, you can create a user in Power IQ with a broader set of roles. All Power IQ web services could then be executed with this user.
In This Chapter
Use Cases ................................................................................................. 7 Functional Description ............................................................................... 7 Technical description ............................................................................... 13 Power Control Examples ......................................................................... 19 FindEDMentities Examples ..................................................................... 22 References .............................................................................................. 28
Chapter 2 SOAP API
Chapter 2: SOAP API
7
Use Cases
Here are some example use cases of the Power IQ web services API.
An asset management system is used to manage/maintain inventory information and Power IQ is kept in sync (data synchronization)
Developers want the ability to remotely switch multiple outlets on or off (power control)
Use case 1: Asset management system/data synchronization
A customer has an asset management system that contains information about floors and racks, such as: „this floor has these racks‟, „this rack has this name and this location‟, and „these Servers are located in this rack‟. The customer would like Power IQ‟s understanding of the world to be based on the information in the asset management system. If a Rack gets added to this system, or a PDU removed, Power IQ should be updated automatically.
Using the API, the customer can write a component to be added to the asset management system that leverages the API of Power IQ to inform Power IQ of certain events ("a new Rack was created, here are the details" or "PDU 192.168.0.1 was just deleted").
Use case 2: Power control
Each developer and tester is responsible for a rack. They go home, and then realize they forgot to switch off their rack. They login to an in-house custom application that utilizes the Power IQ web services API to switch off the power for the rack or one more devices attached to the rack.
Note: Users could also log in to the Power IQ web application remotely to control power.
Functional Description
Fields in Power IQ
There are 2 types of fields in Power IQ, static and dynamic. The static fields remain within Power IQ (this includes fields like the name of a rack, the customer name of a device, etc). This is the majority of fields. The second type of field is dynamic, in the sense that those fields are retrieved from the PDU and/or used to update the fields on the PDU itself.
The sections below give an overview of the available fields for each object. Not all fields are required, and not all objects are required for Power IQ to function optimally. For example, information about "Rooms", "Floors" etc are optional and can be skipped.
Chapter 2: SOAP API
8
PDUs
Field Access type Required?
ID Read-only (key) (generated)
IP address Read-only (cannot be changed after initial creation)
Yes
Proxy identifier Read-only (cannot be changed after initial creation)
No
Manufacturer Read-only (provided by PDU) N/a (provided by PDU)
Model Read-only (provided by PDU) N/a (provided by PDU)
Serial number Read-only (provided by PDU) N/a (provided by PDU)
Firmware version Read-only (provided by PDU) N/a (provided by PDU)
Rated voltage Read-only (provided by PDU) N/a (provided by PDU)
Rated current Read-only (provided by PDU) N/a (provided by PDU)
Rated VA Read-only (provided by PDU) N/a (provided by PDU)
Contact person name Read only (provided by PDU) No
PDU name Read only (provided by PDU) No
Location Read only (provided by PDU) No
SNMP version Currently not available. Yes
SNMP community string/user name/other credentials
Currently not available. Yes
Status (OK, Error, Bad Password etc)
Currently not available. N/a (provided by PDU)
Single phase or Three phase Read-only (provided by PDU) N/a (provided by PDU)
Belongs to (which data center, floor, room, aisle, row or rack this PDU belongs to)
Read/write No
List of outlets with the name and power state of each outlet
Read-only (power control is available. It‟s a separate API call though).
N/a (provided by PDU)
Device
Field Access type Required?
ID Read-only (key) (generated)
Chapter 2: SOAP API
9
Field Access type Required?
Name Read/write Yes
Customer Read/write No
Device Type Read/write No
Power rating (Watts/VA) Read/write No
Decommissioned? Read/write No
Device groups Read/write No
Outlets connected to (the outlets where this device is drawing its power from)
Read/write No
Custom field 1 Read/write No
Custom field 2 Read/write No
External key Read/write No
Rack this device belongs to Read/write Yes
Device Group
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
Members of the device group Read/write No
Rack
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
Location (GetSpaceId) Read/write No
External key Read/write No
Row, Aisle, Room, Floor or Data Center this Rack belongs to
Read/write Yes
Chapter 2: SOAP API
10
Row
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
External key Read/write No
Aisle, Room, Floor or Data Center this Row belongs to
Read/write Yes
Aisle
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
External key Read/write No
Room, Floor or Data Center this Aisle belongs to
Read/write Yes
Room
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
External key Read/write No
Floor or Data Center this Room belongs to
Read/write Yes
Floor
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
External key Read/write No
Chapter 2: SOAP API
11
Field Access type Required?
Data Center this Floor belongs to Read/write Yes
Data Center
Field Access type Required?
ID Read-only (key) (generated)
Name Read/write Yes
Company name Read/write No
Contact name Read/write No
Phone Read/write No
Email Read/write No
City Read/write No
State/province Read/write No
Country Read/write No
Peak rate ($/kWh) Read/write No
Off-peak rate ($/kWh) Read/write No
Peak begin Read/write No
Peak end Read/write No
CO2 factor Read/write No
Cooling factor Read/write No
Custom field 1 Read/write No
Custom field 2 Read/write No
External key Read/write No
Chapter 2: SOAP API
12
List of operations in the API
Requests and commands
This is a list with API calls that will be available through the Web services API.
The table documents the following:
WSDL Operation: The name of the WSDL operation. This is the "name" attribute of the tag <wsdl:operation> in Power IQ‟s WSDL. It uniquely identifies the operation.
Description: Description of what this operation provides.
Synchronous: Whether or not this is a synchronous call.
WSDL Operation Description Synchronous
createEdmEntity Create an EDM entity Yes
updateEdmEntity Update an EDM entity Yes
deleteEdmEntity Delete an EDM entity Yes
getEdmEntity Get (view) an EDM entity Yes
findEdmEntities Advanced searching for EDM entities
Yes
(not supported) Create a Device Group Yes
(not supported) Update a Device Group Yes
(not supported) Deleting a Device Group Yes
(not supported) Get (view) a Device Group
Yes
(not supported) List Device Groups Yes
outletPowerControl Power Control for one or multiple outlets. Switch outlets on/off.
No
deviceGroupPowerControl Power Control for one Device Group. Switch a group of devices on/off (note: a device group needs to be created before this call can be used)
No
edmEntityPowerControl Power control for an edm entity rack, row, device, etc. This does not include a PDU. To turn off outlets
No
Chapter 2: SOAP API
13
WSDL Operation Description Synchronous
directly on a given PDU use outletPowerControl.
Technical description
Getting started
Enabling the WS API
To get started with the WS API, the API needs to be enabled through the Settings Tab. It is disabled by default.
To enable the Web API:
1. In the Settings tab, click Other Security Settings in the Security and Encryption section.
2. In the Web API Settings, select the Enable Web API checkbox, then click Save.
Port Requirement
The API is available over HTTPS only (port 443).
WSDL Files
There are 3 separate WSDL files. They can be found on your Power IQ instance.
The WSDL files are not accessible unless the web API has been enabled. You may have to "View Page Source" after the page has loaded.
Assuming that poweriq.example.com is your Power IQ‟s hostname:
https://poweriq.example.com/api/PowerControlService/?WSDL – operations related to Power Control
https://poweriq.example.com/api/EdmService/?WSDL – operations related to creatng, searching, viewing, updating, and removing EDM entities (PDUs, racks, datacenters)
https://poweriq.example.com/api/JobService/?WSDL – operations necessary for asynchronous operations (jobs)
Chapter 2: SOAP API
14
Supported Technologies
Development Language: Java
Web Service Framework: Axis, Axis2 and CXF
Security
All users that can authenticate in the web UI will also be able to authenticate themselves through web services. The web services API uses the WS-Security UserNameToken profile.
Each web service request requires the UserNameToken. During each request the UserNameToken is used to authenticate the user. There is no need to call an explicit „login‟ method for example.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:q0="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:q1="http://www.raritan.com/poweriq/integration/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<q0:Security>
<UsernameToken>
<Username>admin</Username>
<Password>raritan</Password>
</UsernameToken>
</q0:Security>
</soapenv:Header>
<soapenv:Body>
<q1:outletPowerControl>
<q1:command>
<q1:outlet>
<q1:outletId>12</q1:outletId>
<q1:pduId>12</q1:pduId>
</q1:outlet>
<q1:state>On</q1:state>
</q1:command>
</q1:outletPowerControl>
</soapenv:Body>
</soapenv:Envelope>
Chapter 2: SOAP API
15
Authorization
Permissions to act on objects and perform actions will be based on the current scheme used in Power IQ. Administrators will setup users, groups, and roles within the administration page. This setup will work the same in the UI as it does in a similar web service call.
Example:
User "Sammy" is given the Power Control role on rack1 by a Power IQ administrator through the web user interface.
When Sammy invokes a web service to control the power in rack1, Power IQ will use his user, group, and role information to determine if he is allowed to control the power in rack1. In this case, Sammy will be allowed to control the power of rack1.
Synchronous and Asynchronous Method Calls
Asynchronous calls are limited to power control operations. As a general rule, anything that involves Power IQ communicating with PDUs is set up asynchronously. The WS API will return a Job ID that can be used in future calls to get the status of the request.
In those cases, the calling application needs to verify after the fact what happened. A job will either be ACTIVE or COMPLETE. If a job is COMPLETE, a flag „hasErrors‟ will indicate if there were any errors while executing this job. The details of the errors are available through the GetJobMessages method.
Chapter 2: SOAP API
16
Synchronous Example
Asynchronous Example, Successful Job
Request: Power control: Switch Device 123 off
Reponse: Your Job ID is 4321
Request: What‟s the status of job 4321?
Response: Job 4321 has been completed.
Chapter 2: SOAP API
17
Chapter 2: SOAP API
18
Asynchronous Example, Job with a Problem
Internationalization
The API is not internationalized. Texts returned will be in English. Time stamps will be in the United States Eastern Standard timezone.
Chapter 2: SOAP API
19
Power Control Examples
If you are writing an application that allows a user to do power control operations through Power IQ‟s API, here is an example of how this can be implemented. This shows both synchronous and asynchronous commands.
Use case:
A example application needs to display the power status of a device and give the user the option to turn the device on or off. The example application stores the external key and uses it to identify the device.
Steps:
1. Ask Power IQ what the current power state of the device is (on or off) in order to display this to the user
2. Switch the device off using Power IQ
3. Verify if the "switch off" command was successful.
Step 1: Current state of device
The example application knows that the external key is "device-0044".
The first call gets the current power state of the device using the findEdmEntities method.
<?xml version="1.0" encoding="UTF-8"?>
<typens:findEdmEntities xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:type>Device</typens:type>
<typens:query>
<typens:ordering>
<typens:order direction="ascending" field="name"/>
</typens:ordering>
<typens:conditions>
<typens:condition field="externalKey" value="device-0044"/>
</typens:conditions>
<typens:paging limit="25" offset="0"/>
</typens:query>
</typens:findEdmEntities>
The response would be:
Chapter 2: SOAP API
20
<?xml version="1.0" encoding="UTF-8"?>
<typens:findEdmEntitiesResponse
xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:result>
<typens:message>Found one edm entity</typens:message>
</typens:result>
<typens:entities>
<typens:device>
<typens:id>1</typens:id>
<typens:name>My Device Name</typens:name>
<typens:externalKey>device-0044</typens:externalKey>
<typens:customField1>customField1</typens:customField1>
<typens:customField2>customField2</typens:customField2>
<typens:customer>Some Customer</typens:customer>
<typens:decommissioned>false</typens:decommissioned>
<typens:outlets>
<typens:outlet>
<typens:id>1</typens:id>
<typens:outletId>1</typens:outletId>
<typens:pduId>22</typens:pduId>
<typens:deviceId>1</typens:deviceId>
<typens:name>outlet1</typens:name>
<typens:state>ON</typens:state>
</typens:outlet>
<typens:outlet>
<typens:id>2</typens:id>
<typens:outletId>2</typens:outletId>
<typens:pduId>22</typens:pduId>
<typens:deviceId>1</typens:deviceId>
<typens:name>outlet2</typens:name>
<typens:state>ON</typens:state>
</typens:outlet>
</typens:outlets>
</typens:device>
</typens:entities>
</typens:findEdmEntitiesResponse>
In this example the device has two outlets associated with it, each of which is on.
Step 2: Switch outlet off
The next step is for the example application to request Power IQ to switch the power of this device off. The external key is used in this example to identify the device.
Chapter 2: SOAP API
21
<?xml version="1.0" encoding="UTF-8"?>
<typens:edmEntityPowerControl
xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:commands>
<typens:command>
<typens:device>
<typens:externalKey>device-0044</typens:externalKey>
</typens:device>
<typens:powerControl>
<typens:state>OFF</typens:state>
</typens:powerControl>
</typens:command>
</typens:commands>
</typens:edmEntityPowerControl>
Power IQ will immediately respond with a "Job created successfully message" and the corresponding Job ID (in this example it is 1234).
<?xml version="1.0" encoding="UTF-8"?>
<typens:edmEntityPowerControlResponse
xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:result>
<typens:message>Job created successfully</typens:message>
</typens:result>
<typens:job>
<typens:id>1234</typens:id>
</typens:job>
</typens:edmEntityPowerControlResponse>
Step 3: Check status of job
The last step is to verify the status of the job request:
<?xml version="1.0" encoding="UTF-8"?>
<typens:getJob xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:job>
<typens:id>1234</typens:id>
</typens:job>
</typens:getJob>
In this example response, the job is still active, meaning that the power control operation has not completed yet.
Chapter 2: SOAP API
22
<?xml version="1.0" encoding="UTF-8"?>
<typens:getJobResponse xmlns:typens="http://www.raritan.com/poweriq/integration/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.raritan.com/poweriq/integration/types
poweriq-integration.xsd ">
<typens:result>
<typens:message>Found job 1234</typens:message>
</typens:result>
<typens:job>
<typens:id>1234</typens:id>
<typens:description>Job Description</typens:description>
<typens:endTime>Thu Oct 29 17:23:45</typens:endTime>
<typens:startTime>Thu Oct 29 17:22:45</typens:startTime>
<typens:status>ACTIVE</typens:status>
</typens:job>
</typens:getJobResponse>
FindEDMentities Examples
The EdmService findEdmEntities method provides a searching mechanism for locating EDM entities. The following examples illustrate a number of ways in which findEdmEnties can be used. The examples are in XML, with the SOAP elements removed for brevity. You will have to map the XML elements to your xml binding framework accordingly.
Setting the Paging_Limit for EDM Queries
If you see a"Bad file descriptor" error message, try lowering your paging limit.
For example, a query that returns devices information may work best with a paging limit of 75, but a query that returns PDU information may work best with a paging limit of 10.
Chapter 2: SOAP API
23
Returning Multiple Entities Using the IN Predicate
In this example one invocation of the findEdmEntities method is used to retrieve multiple devices by externalKey using the in predicate. Note that queries can only be scoped against one EDM entity type, in the example below, the query will execute against Device entities.
<q1:findEdmEntities
xmlns:q1="http://www.raritan.com/poweriq/integration/
types">
<q1:type>Device</q1:type>
<q1:query>
<q1:ordering>
<q1:order direction="ascending" field="name"/>
</q1:ordering>
<q1:conditions>
<q1:condition>
<q1:field>externalKey</q1:field>
<q1:predicate>in</q1:predicate>
<q1:values>
<q1:value>Device -- 1</q1:value>
<q1:value>Device -- 2</q1:value>
<q1:value>Device -- 3</q1:value>
</q1:values>
</q1:condition>
</q1:conditions>
</q1:query>
</q1:findEdmEntities>
The message above will result in the following sql query execution in Power IQ:
SELECT * FROM "devices" WHERE
(external_key IN (E'Device -- 1',E'Device -- 2',E'Device
-- 3'))
ORDER BY name ASC LIMIT 50 OFFSET 0
Chapter 2: SOAP API
24
Using the LIKE Predicate
This example returns all Device entities whose externalKey has the name “Device” in it.
<q1:findEdmEntities
xmlns:q1="http://www.raritan.com/poweriq/integration/
types">
<q1:type>Device</q1:type>
<q1:query>
<q1:ordering>
<q1:order direction="ascending" field="name"/>
</q1:ordering>
<q1:conditions>
<q1:condition>
<q1:field>externalKey</q1:field>
<q1:predicate>like</q1:predicate>
<q1:values>
<q1:value>Device</q1:value>
</q1:values>
</q1:condition>
</q1:conditions>
</q1:query>
</q1:findEdmEntities>
The message above will result in the following sql query execution in Power IQ:
SELECT * FROM "devices" WHERE
(external_key LIKE E'%Device%')
ORDER BY name ASC LIMIT 50 OFFSET 0
Chapter 2: SOAP API
25
Finding Exact Matches Using the EQUAL Predicate
Use the equal predicate to find exact matches.
<q1:findEdmEntities
xmlns:q1="http://www.raritan.com/poweriq/integration/
types">
<q1:type>Device</q1:type>
<q1:query>
<q1:ordering>
<q1:order direction="ascending" field="name"/>
</q1:ordering>
<q1:conditions>
<q1:condition>
<q1:field>externalKey</q1:field>
<q1:predicate>equal</q1:predicate>
<q1:values>
<q1:value>Device -- 1</q1:value>
</q1:values>
</q1:condition>
</q1:conditions>
</q1:query>
</q1:findEdmEntities>
The message above will result in the following sql query execution in Power IQ:
SELECT * FROM "devices" WHERE
(external_key = E'Device -- 1')
ORDER BY name ASC LIMIT 50 OFFSET 0
Chapter 2: SOAP API
26
Creating Queries With Multiple Conditions
By combining multiple conditions more advanced queries can be made. Currently, each query condition is combined with an AND. At this time there is no way to override the operator used to combine query conditions.
<q1:findEdmEntities
xmlns:q1="http://www.raritan.com/poweriq/integration/
types">
<q1:type>Device</q1:type>
<q1:query>
<q1:ordering>
<q1:order direction="ascending" field="name"/>
</q1:ordering>
<q1:conditions>
<q1:condition>
<q1:field>customer</q1:field>
<q1:predicate>equal</q1:predicate>
<q1:values>
<q1:value>IBM</q1:value>
</q1:values>
</q1:condition>
<q1:condition>
<q1:field>deviceType</q1:field>
<q1:predicate>equal</q1:predicate>
<q1:values>
<q1:value>Oracle Server</q1:value>
</q1:values>
</q1:condition>
</q1:conditions>
</q1:query>
</q1:findEdmEntities>
Chapter 2: SOAP API
27
The message above will result in the following sql query execution in Power IQ:
SELECT * FROM "devices" WHERE
(customer = E'IBM' AND device_type = E'Oracle Server')
ORDER BY name ASC LIMIT 50 OFFSET 0
28
References
Web Services Security (WS-Security)
Version 1.0 05 05 Apr 2002. Updated 01 Mar 2004
http://www.ibm.com/developerworks/library/specification/ws-secure/
Web Services Security UsernameToken Profile 1.0
OASIS Standard 200401, March 2004
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf
Appendix A
29
The REST API is a way to connect to Power IQ. You can use this REST API from virtually any programming language. All communication is done through JSON over HTTPS.
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is a text format that is completely language independent, but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
The Power IQ REST API consists of logical resources and actions that can be taken on them. For example, there is a resource called "asset_strips", and with it you can list all asset strips, look at a single asset strip or make changes to the asset strip.
In This Chapter
Getting started ......................................................................................... 30 Authentication .......................................................................................... 34 Difference Between PUT and GET Requests ......................................... 34 Data Model .............................................................................................. 38 Sorting and Filtering ................................................................................ 41 Synchronous vs. Asynchronous .............................................................. 41 Frequently Asked Questions ................................................................... 42
Chapter 3 REST API
Chapter 3: REST API
30
Getting started
Enable the API
The API is an optional component to Power IQ. It is disabled by default. As an administrator, go to Settings and then Other Security Settings to enable the API. Click Save Web API Settings.
Chapter 3: REST API
31
Setup a Test Environment (RESTClient)
To test and debug your calls, we recommend the following setup:
Mozilla Firefox http://www.getfirefox.net/ (see http://www.getfirefox.net/ - http://www.getfirefox.net/)
The Firefox RESTclient extension: https://addons.mozilla.org/en-us/firefox/addon/restclient/ (see https://addons.mozilla.org/en-us/firefox/addon/restclient/ - https://addons.mozilla.org/en-us/firefox/addon/restclient/)
The Firefox JSONView extension: https://addons.mozilla.org/en-us/firefox/addon/jsonview/ (see https://addons.mozilla.org/en-us/firefox/addon/jsonview/ - https://addons.mozilla.org/en-us/firefox/addon/jsonview/)
Using this setup, you can try out a Power IQ method. For example, you can view all PDUs on the system.
In the RESTclient extension, use this URL.
https://<ip address>/api/v2/pdus
Click Send.
By default, this will do a GET request on that URL. GET requests are for „reading data‟, PUT requests are for „changing data‟ and POST requests are for „creating new data‟. See Difference Between PUT and GET Requests (on page 34) for examples of PUT requests.
Accept HTTPS Certificate
In a newly installed Power IQ, the system is configured with a self-signed certificate. Your browser will warn you about this, since it doesn‟t recognize the issuer. If you have not already accepted that certificate in a browser, RESTClient will give the following error.
Chapter 3: REST API
32
To fix this, open the Power IQ URL in a browser and accept the certificate. RESTClient will now connect.
Chapter 3: REST API
33
Click "Formatted JSON" to see the response as a formatted JSON call.
Chapter 3: REST API
34
Authentication
To access the API calls, your application needs to authenticate itself. The REST API uses Basic Access Authentication (http://en.wikipedia.org/wiki/Basic_access_authentication (see http://en.wikipedia.org/wiki/basic_access_authentication - http://en.wikipedia.org/wiki/basic_access_authentication)).
Every HTTP request should include an extra request header with the Base64 encoded username and password. The API always uses HTTPS, so all information is transmitted encrypted, including username and password.
For example, if your username is "admin" and your password is "raritan", include in every HTTP request the following ("YWRtaW46cmFyaXRhbg==" is Base64 of "admin:raritan").
GET /api/v2/pdus (see https://192.168.43.196/api/v2/pdus
- https://192.168.43.196/api/v2/pdus) HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46cmFyaXRhbg==
Most programming languages and libraries provide built-in support for Basic Access Authentication.
Note: In the Firefox REST Client, click Login, and the client will handle this for you.
Difference Between PUT and GET Requests
The majority of the method calls in the REST API are read-only. Those are provided through GET requests. Those are the same type requests that a web browser would issue.
There are a few method calls that allow you to make changes to Power IQ. Those are implemented using PUT requests.
Important: When issuing a PUT request, add the following header to each request:
Content-Type: application/json
Chapter 3: REST API
35
Example: Changing the Light on an Asset Strip
This example shows how to use the API to find out which asset strips are connected to Power IQ, and then shows how to use a PUT request to change the color of a light on the asset strip.
https://<ip address>/api/v2/asset_strips
{"asset_strips":[{"default_disconnected_led_color":nu
ll,"name":"FooBar","updated_at":"2011/03/31 10:23:34
-0400","id":2,"pdu_id":24,"default_connected_led_colo
r":null,"state":"available","ordinal":1,"created_at":
"2011/03/29 08:53:18 -0400"}]}
An important field here is the ID, which is 2 in this example. The ID allows you to interrogate the asset management strip by itself. This is not strictly necessary in this example, since the list with strips gave all the details, but the principle is important.
https://<ip address>/api/v2/asset_strips/2
{"asset_strip":{"default_disconnected_led_color":null
,"name":"FooBar","updated_at":"2011/03/31 10:23:34
-0400","id":2,"pdu_id":24,"default_connected_led_colo
r":null,"state":"available","ordinal":1,"created_at":
"2011/03/29 08:53:18 -0400"}}
To find out which rack units the asset strip consists of, use the following call.
https://<ip address>/api/v2/asset_strips/2/rack_units
This returns a fairly large piece of JSON, abbreviated here for readability. It is a list of rack units for asset strip 2.
Chapter 3: REST API
36
{"rack_units":[{"updated_at":"2011/03/31 10:23:34
-0400","led_mode":"manual","tag_id":"","id":5,"led_st
ate":"off","led_color":"ffff00","ordinal":4,"created_
at":"2011/03/29 08:53:18
-0400","asset_strip_id":2},{"updated_at":"2011/03/31
10:23:34
-0400","led_mode":"automatic","tag_id":"00001362B164"
,"id":6,"led_state":"on","led_color":"0000ff","ordina
l":5,"created_at":"2011/03/29 08:53:18
-0400","asset_strip_id":2},{"updated_at":"2011/03/31
10:23:34
-0400","led_mode":"manual","tag_id":"","id":7,"led_st
ate":"on","led_color":"ffffff","ordinal":6,"created_a
t":"2011/03/29 08:53:18
-0400","asset_strip_id":2},{"updated_at":"2011/03/31
10:23:34
-0400","led_mode":"automatic","tag_id":"00001362B211"
,"id":8,"led_state":"on","led_color":"0000ff","ordina
l":7,"created_at":"2011/03/29 08:53:18
-0400","asset_strip_id":2},
… abbreviated for readability …
{"updated_at":"2011/03/31 10:23:34
-0400","led_mode":"manual","tag_id":"","id":4,"led_st
ate":"on","led_color":"ff0000","ordinal":3,"created_a
t":"2011/03/29 08:53:18 -0400","asset_strip_id":2}]}
This example will show how to change the light of the 7th light of the asset strip (ordinal = 7, but the id = 8, as you can see in the JSON).
To look at the 7th light of the asset strip in more detail, use this URL:
https://<ip address>/api/v2/rack_units/8 (see
https://192.168.43.196/api/v2/rack_units/8 -
https://192.168.43.196/api/v2/rack_units/8)
This returns:
{"rack_unit":{"updated_at":"2011/03/31 10:53:34
-0400","led_mode":"automatic","tag_id":"00001362B211"
,"id":8,"led_state":"on","led_color":"0000ff","ordina
l":7,"created_at":"2011/03/29 08:53:18
-0400","asset_strip_id":2}}
To make the light of an asset strip change color, you can do a PUT on the same URL:
PUT on https://<ip address>/api/v2/rack_units/8 (see
https://192.168.43.196/api/v2/rack_units/8 -
https://192.168.43.196/api/v2/rack_units/8)
With request body:
rack_unit: { led_color: "ffffff", led_state: "blinking"
}
Example values for led-state:
Chapter 3: REST API
37
on
off
blinking
Example led color values:
Green 008000
Yellow ffff00
Blue 000055
DarkBlue 0000ff
Purple 800080
Red ff0000
LightRed ff0033
Orange ffa500
White ffffff
Black 000000
Cyan/Aqua 00ffff
Green/Lime 00ff00
Chapter 3: REST API
38
Data Model
The data model used in the REST API is the same as in other parts of the application such as the ODBC tables and the SOAP API. Field names can differ slightly. Here is the relationship between various objects.
Overview of API calls
Here is a list of all available API calls in the REST API.
Note that where it says ":id" or ":pdu_id", you should use the ID of the object that you are interested in.
For example, to use API call "/api/v2/pdus/:id" for PDU number 4, use "/api/v2/pdus/4".
PDUs
/api/v2/pdus Retrieve a listing of all PDUs
/api/v2/pdus/:id Retrieve a specific PDU
Chapter 3: REST API
39
/api/v2/pdus/:pdu_id/sensors Retrieve the environmental sensors for a PDU
/api/v2/pdus/:pdu_id/outlets Retrieve the outlets for a PDU
/api/v2/pdus/:pdu_id/asset_strips Retrieve the asset strips for a PDU
/api/v2/outlets Retrieve a listing of all outlets for all PDUs
To be more specific, use criteria like this:
https://<ip address>/api/v2/outlets?pdu_id=27
/api/v2/outlets/:id Retrieve a specific outlet
/api/v2/sensors Retrieve a listing of all environmental sensors for all PDUs
To be more specific, use criteria like this:
https://<ip address>/api/v2/sensors?pdu_id=27
/api/v2/sensors/:id Retrieve a specific environmental sensor
IT Devices
/api/v2/devices Retrieve a listing of all IT devices
/api/v2/devices/:id Retrieve a specific device
/api/v2/devices/:device_id/outlets Show all outlets for a device
Asset Strips
/api/v2/asset_strips Retrieve a listing of all asset strips
/api/v2/asset_strips/:id (read-write) Retrieve a specific asset strip
/api/v2/asset_strips/:asset_strip_id/rack_units Retrieve the rack units for a specific asset strip
/api/v2/rack_units Retrieve all rack units in the system. You can filter on the various fields.
For example, to see all rack_units that are "on", use this:
https://<ip address>/api/v2/rack_units?led_state=on (see https://192.168.43.196/api/v2/rack_units?led_state=on - https://192.168.43.196/api/v2/rack_units?led_state=on)
PUT or GET /api/v2/rack_units/:id This is an important URL.
If you do a GET, you‟ll see the status of the rack units‟ lights.
If you do a PUT, you can actually change the value of
Chapter 3: REST API
40
the lights.
See Example: Changing the Light on an Asset Strip (on page 35).
Events
/api/v2/events Retrieve a listing of all events.
/api/v2/events/:id Retrieve a specific event.
/api/v2/outlets/:outlet_id/events See the events associated with a given outlet.
/api/v2/pdus/:pdu_id/events See the events associated with a given PDU.
/api/v2/sensors/:sensor_id/events See the events associated with a given environmental sensor.
PUT /api/v2/events/clear_batch Clear several events at once.
PUT /api/v2/events/:id/clear Clear a specific event.
Jobs
Jobs are used for asynchronous method invocations. See Synchronous vs. Asynchronous (on page 41).
The first two methods are the most important:
Give the status of a specific job
Show the detailed messages contained in each job
/api/v2/jobs/:id Shows the status of a given job.
/api/v2/jobs/:job_id/messages Shows the job messages for a given job.
/api/v2/job_messages Shows all job messages.
/api/v2/job_messages/:id Shows a specific job message.
Miscellaneous
/api/v2/system_info Provides various system fields, such as the Power IQ version number.
Chapter 3: REST API
41
Sorting and Filtering
All listing methods support sorting and filtering.
For example, by default the rack units are returned unsorted, but if you prefer you can see them sorted with a call like this:
https://<ip
address>/api/v2/asset_strips/2/rack_units?ascend_by_i
d=1
Use parameters ascend_by_id=1 and descent_by_id=1 to sort by id. Similarly, you can sort on other fields.
Synchronous vs. Asynchronous
Most methods calls in the REST API execute within 1 second. If your request spans multiple PDUs, or multiple asset management strips, or a huge amount of data, the request may take longer. In that case it‟s faster to switch to asynchronous processing.
To switch to asynchronous processing:
Add this parameter to your URL:
async=true
When asynchronous mode is enabled, the method call will return immediately with a job ID. You can use the job ID to interrogate the system. This is exactly how the SOAP Power Control API works.
The default behavior in the REST API is for all methods to be synchronous.
Chapter 3: REST API
42
Frequently Asked Questions
Why do I see "Error: could not connect to server" in the RESTclient?
Make sure that Power IQ is up and running, and that the API is enabled on Power IQ.
Then check that the HTTPS certificate is okay: if you are using a self-signed certificate on Power IQ (this is the default setting), you will need to accept the certificate using regular browser before you can use the RESTClient.
Chapter 3: REST API
43
Why do I get NoMethodError in my response?
For PUT and POST requests, remember to add the correct JSON content type request header:
Content-Type: application/json
45
A
Accept HTTPS Certificate • 31 Aisle • 10 Asset Strips • 39 Asynchronous Example, Job with a Problem •
18 Asynchronous Example, Successful Job • 16 Authentication • 34 Authorization • 15
C
Creating Queries With Multiple Conditions • 26
D
Data Center • 11 Data Model • 38 Device • 8 Device Group • 9 Difference Between PUT and GET Requests •
31, 34
E
Enable the API • 30 Enabling the WS API • 13 Events • 40 Example
Changing the Light on an Asset Strip • 35, 39
F
Fields in Power IQ • 7 FindEDMentities Examples • 22 Finding Exact Matches Using the EQUAL
Predicate • 25 Floor • 10 Frequently Asked Questions • 42 Functional Description • 6, 7
G
Getting started • 6, 13, 30
I
Internationalization • 18 Introduction • 5 IT Devices • 39
J
Jobs • 40
L
List of operations in the API • 12
M
Miscellaneous • 40
O
Overview of API calls • 38
P
PDUs • 8, 38 Port Requirement • 13 Power Control Examples • 19
R
Rack • 9 References • 28 Requests and commands • 12 REST API • 29 Returning Multiple Entities Using the IN
Predicate • 23 Room • 10 Row • 10
S
Security • 14 Setting the Paging_Limit for EDM Queries • 22 Setup a Test Environment (RESTClient) • 31 SOAP API • 6 Sorting and Filtering • 41 Step 1
Current state of device • 19 Step 2
Switch outlet off • 20 Step 3
Check status of job • 21 Supported Technologies • 14 Synchronous and Asynchronous Method Calls
• 15 Synchronous Example • 16 Synchronous vs. Asynchronous • 40, 41
Index
Index
46
T
Technical description • 13
U
Use case 1 Asset management system/data
synchronization • 7 Use case 2
Power control • 7 Use Cases • 7 Using the LIKE Predicate • 24
W
Why do I get NoMethodError in my response? • 43
Why do I see • 42 WSDL Files • 13
U.S./Canada/Latin America Monday - Friday 8 a.m. - 6 p.m. ET Phone: 800-724-8090 or 732-764-8886 For CommandCenter NOC: Press 6, then Press 1 For CommandCenter Secure Gateway: Press 6, then Press 2 Fax: 732-764-8887 Email for CommandCenter NOC: [email protected] Email for all other products: [email protected]
China
Beijing Monday - Friday 9 a.m. - 6 p.m. local time Phone: +86-10-88091890
Shanghai Monday - Friday 9 a.m. - 6 p.m. local time Phone: +86-21-5425-2499
GuangZhou Monday - Friday 9 a.m. - 6 p.m. local time Phone: +86-20-8755-5561
India Monday - Friday 9 a.m. - 6 p.m. local time Phone: +91-124-410-7881
Japan Monday - Friday 9:30 a.m. - 5:30 p.m. local time Phone: +81-3-3523-5991 Email: [email protected]
Europe
Europe Monday - Friday 8:30 a.m. - 5 p.m. GMT+1 CET Phone: +31-10-2844040 Email: [email protected]
United Kingdom Monday - Friday 8:30 a.m. to 5 p.m. GMT Phone +44(0)20-7090-1390
France Monday - Friday 8:30 a.m. - 5 p.m. GMT+1 CET Phone: +33-1-47-56-20-39
Germany Monday - Friday 8:30 a.m. - 5:30 p.m. GMT+1 CET Phone: +49-20-17-47-98-0 Email: [email protected]
Melbourne, Australia Monday - Friday 9:00 a.m. - 6 p.m. local time Phone: +61-3-9866-6887
Taiwan Monday - Friday 9 a.m. - 6 p.m. GMT -5 Standard -4 Daylight Phone: +886-2-8919-1333 Email: [email protected]