Web Services API Guide, Cisco DCNM for LAN, Release 5.x
Overview
Download this chapter
OverviewOverview
Download the complete book
Cisco DCNM Web Services API Guide, Release 5.xCisco DCNM Web Services API Guide, Release 5.x (PDF - 3 MB)
 Feedback

Table Of Contents

Overview

Information About Web Services

SOAP Messages

SOAP Message to Create Session ID

SOAP Message to Make API Call

Error Handling

Licensing Requirements for Web Services

Additional References

Related Documents

Standards


Overview

This chapter describes the Data Center Network Management (DCNM) web services' application program interface (API).

This chapter includes the following sections:

•Information About Web Services

•Licensing Requirements for Web Services

•Additional References

Information About Web Services

You can configure NX-OS devices by using the Cisco DCNM web services' API on the DCNM server. You create XML-based API requests by using the SOAP protocol. The DCNM server configures devices using the XML management interface. For more information about the XML management interface, see the Cisco Nexus 7000 Series NX-OS XML Management Interface User Guide, Release 4.2.

The web services' API provides a subset of the features available in the DCNM client. For information about DCNM, see the Cisco DCNM Fundamentals Configuration Guide, Release 4.2.

This section includes the following topics:

•SOAP Messages

•Error Handling

SOAP Messages

The SOAP messages that you exchange with the DCNM server contain a user ID and password in the header and an API call in the body.

You can obtain the XSD and WSDL files that describe the DCNM web services on the DCNM server in the ws-client folder of the DCNM installation directory. By default, the DCNM server is installed at C:\Program Files\Cisco Systems\DCNM.

For more information about SOAP, see http://www.w3.org/TR/soap.

This section includes the following topics:

•SOAP Message to Create Session ID

•SOAP Message to Make API Call

SOAP Message to Create Session ID

Example 1-1 shows the initial SOAP message that you send to obtain a session ID with the createSessionID method in the SecurityApp service. The SecurityApp URL must be in the following format:

http://<dcnm-server-ipAddress>:<port-number>/dcnm-ws-server/security-ws

dcnm-server-ipAddress—IP Address of the DCNM server.

port-number—The HTTP port on which the message to be posted. The default port number is 8080.

All subsequent SOAP messages use the returned session ID. You use the createSessionID method in the Security AppService and specify the user ID and password of the DCNM server.

Example 1-1 SOAP Message to Obtain Session ID 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

            <SOAP-ENV:Header>

                        <m:credentialHeader 
xmlns:m="http://security.app.ws.dcm.dcbu.cisco.com/SecurityAppService">

                                    <userId>admin</userId>

                                    <password>admin</password>

                        </m:credentialHeader>

            </SOAP-ENV:Header>

            <SOAP-ENV:Body>

                        <m:createSessionId 
xmlns:m="http://security.app.ws.dcm.dcbu.cisco.com/SecurityAppService">

                        <aOpContext/>

                        </m:createSessionId>

            </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Example 1-2 shows the returned session ID "9A7C0399AC161F3601FEB227E2ADA634" that you use in subsequent API calls.

Example 1-2 Response to SOAP Message to Obtain Session ID 

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

            <env:Header/>

            <env:Body>

            <m:createSessionIdResponse 
xmlns:m="http://security.app.ws.dcm.dcbu.cisco.com/SecurityAppService">

            <result xmlns:basictypes="http://basictypes.dcm.dcbu.cisco.com" 
xmlns:common="http://common.dcm.dcbu.cisco.com" 
xmlns:datatype="http://datatype.model.dcm.dcbu.cisco.com" 
xmlns:enumkind="http://enumkind.model.dcm.dcbu.cisco.com" 
xmlns:util="http://util.common.dcm.dcbu.cisco.com" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.w3.org/2001/XMLSchema xml.xsd" 
xsi:type="xs:string">9A7C0399AC161F3601FEB227E2ADA634</result>

            </m:createSessionIdResponse>

            </env:Body>

</env:Envelope>

SOAP Message to Make API Call

Example 1-3 shows the SOAP message that you send to request the chassis inventory with method getAllChassisInNetwork in the InventoryApp service. The InventoryApp URL must be in the following format:

http://<dcnm-server-ipAddress>:<port-number>/dcnm-ws-server/inventory-ws

dcnm-server-ipAddress—IP Address of the DCNM server.

port-number—The HTTP port on which the message to be posted. The default port number is 8080.

Example 1-3 SOAP Message to Request Chassis Inventory 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

            <SOAP-ENV:Header>

                        <m:credentialHeader 
xmlns:m="http://inventory.app.ws.dcm.dcbu.cisco.com/InventoryAppService">

                        <sessionId>9A7C0399AC161F3601FEB227E2ADA634</sessionId>

                        </m:credentialHeader>

            </SOAP-ENV:Header>

            <SOAP-ENV:Body>

                        <m:getAllChassisInNetwork 
xmlns:m="http://inventory.app.ws.dcm.dcbu.cisco.com/InventoryAppService">

                        <opContext/>

                        </m:getAllChassisInNetwork>

            </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Example 1-4 shows the response to the request for chassis inventory.

Example 1-4 Response to SOAP Message to Request Chassis Inventory 

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

 <env:Header/>

 <env:Body>

 <m:getAllChassisInNetworkResponse 
xmlns:m="http://inventory.app.ws.dcm.dcbu.cisco.com/InventoryAppService">

  <return collectionType="List" xmlns:basictypes="http://basictypes.dcm.dcbu.cisco.com" 
xmlns:common="http://common.dcm.dcbu.cisco.com" 
xmlns:datatype="http://datatype.model.dcm.dcbu.cisco.com" 
xmlns:enumkind="http://enumkind.model.dcm.dcbu.cisco.com" 
xmlns:physical="http://physical.model.dcm.dcbu.cisco.com" 
xmlns:tns="http://physical.model.dcm.dcbu.cisco.com" 
xmlns:util="http://util.common.dcm.dcbu.cisco.com" 
xmlns:vdc="http://vdc.model.dcm.dcbu.cisco.com" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://physical.model.dcm.dcbu.cisco.com physical.xsd" 
xsi:type="physical:Chassis_ListType">

  <itemList xsi:type="physical:Chassis">

   <instClassName>com.cisco.dcbu.dcm.model.physical.Chassis</instClassName>

   <instanceClassId>6143</instanceClassId>

   
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

   <instanceState>Unmodified</instanceState>

   <version>3</version>

   <description>Nexus7000 C7010 (10 Slot) Chassis</description>

   <name>Chassis</name>

   <productId>N7K-C7010</productId>

   <serialNumber>TBM11256510</serialNumber>

   <chassisPowerSupplyRef xsi:type="physical:ChassisPowerSupplySetting">

   
<instClassName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplySetting</instClassName>

   <powerSupplyRedundancyMode>Redundant</powerSupplyRedundancyMode>

   </chassisPowerSupplyRef>

   <chassisPowerSupplyStatusRef xsi:type="physical:ChassisPowerSupplyStatus">

   
<instClassName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplyStatus</instClassName>

   <instanceClassId>6252</instanceClassId>

   
<instanceName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplyStatus:neId=2,chassisId=
TBM11256510</instanceName>

   <instanceState>Unmodified</instanceState>

   <version>0</version>

   <availablePowerSupply>2329.00</availablePowerSupply>

   <operationalRedundancyStatus>Redundant</operationalRedundancyStatus>

   <totalPowerSupply>5480.00</totalPowerSupply>

   <usedPowerSupply>3151.0</usedPowerSupply>

   </chassisPowerSupplyStatusRef>

   <networkElementRef xsi:type="vdc:NetworkElement">

   <instClassName>com.cisco.dcbu.dcm.model.vdc.NetworkElement</instClassName>

   <instanceClassId>2</instanceClassId>

   <instanceName>com.cisco.dcbu.dcm.model.vdc.NetworkElement:neId=2</instanceName>

   <instanceState>Unmodified</instanceState>

   <version>6</version>

   <abstractNetworkElementStatusRef xsi:type="vdc:AbstractNetworkElementStatus">

    
<instClassName>com.cisco.dcbu.dcm.model.vdc.AbstractNetworkElementStatus</instClassName>

    <instanceClassId>6146</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.vdc.AbstractNetworkElementStatus:neId=2</instanceNa
me>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <mgmtState>Managed</mgmtState>

    <userId>administration</userId>

   </abstractNetworkElementStatusRef>

   <hostName>DCNM-9</hostName>

   <mgmtIpAddress>172.27.139.76</mgmtIpAddress>

   <platformName>Nexus7000</platformName>

   <platformType>Cisco Nexus7000 Series</platformType>

   <platformVersion>4.0(1)</platformVersion>

   <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

   </chassisRef>

   </networkElementRef>

   <redundancySettingsRef xsi:type="physical:RedundancySetting">

   <instClassName>com.cisco.dcbu.dcm.model.physical.RedundancySetting</instClassName>

   <redundancyMode>HA</redundancyMode>

   </redundancySettingsRef>

   <redundancyStatusRef xsi:type="physical:RedundancyStatus">

   <instClassName>com.cisco.dcbu.dcm.model.physical.RedundancyStatus</instClassName>

   <instanceClassId>6250</instanceClassId>

   
<instanceName>com.cisco.dcbu.dcm.model.physical.RedundancyStatus:neId=2,chassisId=TBM11256
510</instanceName>

   <instanceState>Unmodified</instanceState>

   <version>0</version>

   <operationalRedundancyMode>None</operationalRedundancyMode>

   </redundancyStatusRef>

   <slotCol collectionType="Set" xsi:type="physical:Slot_SetType">

   <itemSet xsi:type="physical:Slot">

    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>

    <instanceClassId>6150</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=3</instanceName>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

    </chassisRef>

    <slotNumber>3</slotNumber>

   </itemSet>

   <itemSet xsi:type="physical:Slot">

    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>

    <instanceClassId>6148</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=1</instanceName>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

    </chassisRef>

    <slotNumber>1</slotNumber>

   </itemSet>

   <itemSet xsi:type="physical:Slot">

    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>

    <instanceClassId>6152</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=5</instanceName>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

    </chassisRef>

    <slotNumber>5</slotNumber>

   </itemSet>

   <itemSet xsi:type="physical:Slot">

    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>

    <instanceClassId>6156</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=12</instanceName>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

    </chassisRef>

    <slotNumber>12</slotNumber>

   </itemSet>

   <itemSet xsi:type="physical:Slot">

    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>

    <instanceClassId>6154</instanceClassId>

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=11</instanceName>

    <instanceState>Unmodified</instanceState>

    <version>1</version>

    <chassisRef xsi:type="physical:Chassis">

    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>

    </chassisRef>

    <slotNumber>11</slotNumber>

   </itemSet>

   </slotCol>

  </itemList>

  </return>

 </m:getAllChassisInNetworkResponse>

 </env:Body>

</env:Envelope>

Error Handling

Exceptions that can occur are listed under each method.

Licensing Requirements for Web Services

The following table shows the licensing requirements for this feature:

Product
License Requirement

Cisco DCNM

Web services requires no license. Any feature not included in a license package is bundled with the Cisco DCNM and is provided at no charge to you. For a complete explanation of the Cisco DCNM licensing scheme, see the Cisco DCNM Installation and Licensing Guide.


Additional References

For additional information related to implementing the Web Services API, see the following sections:

•Related Documents

•Standards

Related Documents

Related Topic
Document Title

XML management interface

Cisco Nexus 7000 Series NX-OS XML Management Interface User Guide, Release 4.2

DCNM client

Cisco DCNM Fundamentals Configuration Guide, Release 4.2


Standards

Standards
Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.

—