Power IQ WS-API Programming Guidesupport.raritan.com/Power-IQ/Version-3.0.0/user-guides/... ·...

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



Chapter 2: SOAP API

9


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


External key Read/write No

Rack this device belongs to Read/write Yes

Device Group



Name Read/write Yes

Members of the device group Read/write No

Rack



Name Read/write Yes

Location (GetSpaceId) Read/write No


Row, Aisle, Room, Floor or Data Center this Rack belongs to

Read/write Yes

Chapter 2: SOAP API

10

Row



Name Read/write Yes


Aisle, Room, Floor or Data Center this Row belongs to

Read/write Yes

Aisle



Name Read/write Yes


Room, Floor or Data Center this Aisle belongs to

Read/write Yes

Room



Name Read/write Yes


Floor or Data Center this Room belongs to

Read/write Yes

Floor



Name Read/write Yes


Chapter 2: SOAP API

11


Data Center this Floor belongs to Read/write Yes

Data Center



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




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.


<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


<typens:findEdmEntitiesResponse

xmlns:typens="http://www.raritan.com/poweriq/integration/types"




<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: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: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


<typens:edmEntityPowerControl





<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).


<typens:edmEntityPowerControlResponse





<typens:result>

<typens:message>Job created successfully</typens:message>

</typens:result>

<typens:job>


</typens:job>

</typens:edmEntityPowerControlResponse>

Step 3: Check status of job

The last step is to verify the status of the job request:


<typens:getJob xmlns:typens="http://www.raritan.com/poweriq/integration/types"




<typens:job>


</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


<typens:getJobResponse xmlns:typens="http://www.raritan.com/poweriq/integration/types"




<typens:result>

<typens:message>Found job 1234</typens:message>

</typens:result>

<typens:job>


<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: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


types">


<q1:query>

<q1:ordering>


</q1:ordering>

<q1:conditions>

<q1:condition>


<q1:predicate>like</q1:predicate>

<q1:values>

<q1:value>Device</q1:value>

</q1:values>

</q1:condition>

</q1:conditions>

</q1:query>




(external_key LIKE E'%Device%')


Chapter 2: SOAP API

25

Finding Exact Matches Using the EQUAL Predicate

Use the equal predicate to find exact matches.

<q1:findEdmEntities


types">


<q1:query>

<q1:ordering>


</q1:ordering>

<q1:conditions>

<q1:condition>


<q1:predicate>equal</q1:predicate>

<q1:values>


</q1:values>

</q1:condition>

</q1:conditions>

</q1:query>




(external_key = E'Device -- 1')


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


types">


<q1:query>

<q1:ordering>


</q1:ordering>

<q1:conditions>

<q1:condition>

<q1:field>customer</q1:field>


<q1:values>

<q1:value>IBM</q1:value>

</q1:values>

</q1:condition>

<q1:condition>

<q1:field>deviceType</q1:field>


<q1:values>

<q1:value>Oracle Server</q1:value>

</q1:values>

</q1:condition>

</q1:conditions>

</q1:query>


Chapter 2: SOAP API

27



(customer = E'IBM' AND device_type = E'Oracle Server')


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.

http://www.getfirefox.net/

https://addons.mozilla.org/en-us/firefox/addon/restclient/

https://addons.mozilla.org/en-us/firefox/addon/jsonview/

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

http://en.wikipedia.org/wiki/basic_access_authentication

https://192.168.43.196/api/v2/pdus

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


10:23:34


ate":"on","led_color":"ffffff","ordinal":6,"created_a

t":"2011/03/29 08:53:18


10:23:34



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


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



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:

https://192.168.43.196/api/v2/rack_units/8

https://192.168.43.196/api/v2/rack_units/8

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

https://192.168.43.196/api/v2/rack_units?led_state=on

https://192.168.43.196/api/v2/rack_units?led_state=on

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]

Date post:	04-Mar-2021
Category:	Documents
Upload:	others
View:	4 times
Download:	0 times

Power IQ WS-API Programming Guidesupport.raritan.com/Power-IQ/Version-3.0.0/user-guides/... ·...

Documents