Fabric Manager Web Services
This chapter describes the Fabric Manager Web Services (FMWS) application program interface (API). This chapter includes the following sections:
•About Fabric Manager Web Services
•Web Services Specifications
•Logon Service
•San Service
•Service Endpoint Interface (SEI)
•Methods
•Error Codes
About Fabric Manager Web Services
The Cisco Fabric Manager Web Services (FMWS) enables third-party vendors to access Fabric Manager core software functionalities as remote procedure calls. Web Services extend the World Wide Web infrastructure to provide a method to softwares connecting to other software applications. Applications access Web Services using many protocols and data formats such as HTTP, HTTPS, XML, and SOAP. Web Services combine the best aspects of component-based development and the web. Web Services makes Fabric Manager an enterprise class application allowing it to be interoperable with other software platforms.
This chapter defines the APIs exposed by the Fabric Manager Web Services feature.
Web Services Specifications
Web Services specifications compose together to provide interoperable protocols for security, communication and syntax for representing data.
XML
XML is the data format that defines the structure of the message. XML Web Services architecture allows programs written in different languages on different platforms to communicate with each other in a standards-based way. XML Web Services expose useful functionality to Web users through a standard Web protocol (SOAP).
SOAP
Simple Object Access Protocol (SOAP) is the communications protocol for Web Services. SOAP is a specification that defines the XML format for messages. The advantage of SOAP is that it has been implemented on many different hardware and software platforms.
HTTP/HTTPS
HTTP/HTTPS is the transport layer of the service. HTTP/HTTPS allows data to traverse the network easily and is widely accepted. It is also considered as platform neutral. Every Fabric Manager Web Services operation is through HTTP/HTTPS.
WDSL
A WSDL definition is an XML document with a root definition element from the http://schemas.xmlsoap.org/wsdl/ namespace. Fabric Manager Web Services uses the WSDL document to publish which operations of Fabric Manager are available. The definitions element may contain several other elements including types, message, portType, binding, and service, all of which come from the namespace. WSDL is published on FMServer at http://localhost/LogonWSService/LogonWS?wsdl
Logon Service
LogonWS makes IdentityManager's operations available as Web Service calls. LogonWS allows the following operations:
requestToken
This method returns a token string that must be passed in as the header of the SOAP message. Once the username and password is authentication using Fabric Manager's SecurityManager, the token is generated and is kept valid for the number of milliseconds specified in the expiration argument.
Parameters
username—Name of the user.
password—Password of the user.
expiration—Time (in milliseconds).
Return Value
Session token.
Error
Error code: 201—Invalid argument in Web Service exception.
validateToken
This method returns true or false depending on the validity of the token. If the token has expired, it returns false, or else it returns true.
Parameters
token—Session Token.
Return Value
Boolean value "True" if the Fabric Manager accepts the token.
Error
Error code: 201—Invalid argument in Web Service exception.
Authentication or Token
To interact with Fabric Manager Web Services, the user must obtain a token through LogonWS and attach this token to the header message of every SOAP requests. Fabric Manager Web Services verifies user credentials using a unique token string that is administered by LogonWS. At any given time, HTTPS should be deployed to secure the communication channel. The following example displays the format of the header message:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<m:Token xmlns:m="http://www.w3schools.com/transaction/">
</m:Token></SOAP-ENV:Header>
<getFabrics xmlns="http://ep.jaxws.dcbu.cisco.com/"/>
IdentityManager
IdentityManager provide identity services and manage the user credentials that are required by Web Services. It is the token provider who administers and maintains tokens. It authenticates the user, generates tokens, and validates or expires tokens by periodically checking and clearing the cache.
San Service
San Service is an Enterprise Java Beans (EJB) component that manages SAN-related service requests and executes queries on Fabric Manager for information. SanWS checks with IdentityManager for authentication before performing the request. A valid token string tells San Service that the user is a Fabric Manager user and it must honor and execute the request. After retrieving the required information it sends the result back to the user. SanWS logs errors in fms_ws.log.
Service Endpoint Interface (SEI)
Service endpoint interface (SEI) of SanWS defines the operations of the service. These methods are published to the end users.
Methods
getFabrics
Returns the list of all open fabrics.
Return Value
An array of open fabrics.
Error
Error Code: 300— General SAN Service exception.
getFabricByIP
Returns the list of fabrics associated with the IP address of a given switch.
Parameters
ipAddress—IP address of the switch.
Return Value
List of all fabrics associated with the specificIP address.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getFabricByKey
Returns the list of fabrics associated with the specified key.
Parameters
key—Key of the fabric.
Return Value
List of all fabrics associated with the specified key.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getFabricBySwitchKey
Returns the list of fabrics associated with the specified seed switch key (WWN).
Parameters
swkey—Seed switch key of the fabric.
Return Value
List of all fabrics associated with the specified seed switch key.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getSwitchesByFabric
Returns the list of switches associated with the specified fabric key.
Parameters
key—Key of the fabric.
Return Value
List of all fabrics associated with the specified fabric key.
Error
Error Code: 300— General SAN Service exception.
getSwitch
Returns the list of switches on all the fabrics.
Parameters
key—Key of the fabric.
Return Value
List of all fabrics associated with the specified fabric key.
Error
Error Code: 300— General SAN Service exception.
getSwitchByKey
Returns the switch associated with the specified switch key object.
Parameters
key—Key of the fabric.
Return Value
Switch associated with the specified switch key.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getSwitchIPByName
Returns the IP address associated with the specified system name or switch name.
Parameters
sysname—Name of the system or switch.
Return Value
IP address associated with the specified system name.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getSwitchIPByKey
Returns the IP address of the switch associated with the specified WwnKey object.
Parameters
key—WWN Key object.
Return Value
IP address associated with the specifiedWwnKey object.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getNeighborSwitches
Returns the list of neighboring switches associated with the specified WwnKey.
Parameters
key—Wwn Key object.
Return Value
List of neighboring switches associated with the specifiedWwnKey.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
Error code: 302—SAN does not found objects by query key exception.
getVsans
Returns the list of VSANs in the fabric associated with the specified fabric key.
Parameters
key—fabric key object.
Return Value
List of VSANs in the fabric associated with the specified fabric key.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getVsan
Returns the VSAN in the fabric associated with the specified VSAN key object.
Parameters
key—VSAN key object.
Return Value
VSANs in the fabric associated with the specified VSAN key object.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getIsls
Returns the list of ISLs in the VSAN associated with the specified VSAN key.
Parameters
key—VSAN key.
Return Value
Array of ISL objects in the VSAN associated with the specified VSAN key.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
discoverFabric
This API will open the fabric. This function requires the IP address of the seed switch and SNMP credentials.
Parameters
seed—IP address of the seed switch.
user—SNMP Credential.
Return Value
Boolean value is True, if the discovery was successful.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
Error Code: 100— Authentication failure exception.
Error code: 101—Invalid credentials exception.
manageFabric
Returns true or false depending managability of the fabric.
Parameters
key—Fabric key.
Return Value
Returns true if the fabric can be identified ot managed. Returns false if the fabric cannot be identified ot managed.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
unManageFabric
This function is used to unmanage a fabric.
Parameters
key—Fabric key.
Return Value
None.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
closeFabric
This functions is used to un manage and close a fabric.
Parameters
key—Fabric key.
Return Value
None.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
purgeFabric
This functions is used to purge the specified fabric data both from Fabric Manager cache and database.
Parameters
key—Fabric key.
Return Value
None.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
Error code: 302—SAN does not found objects by query key exception.
getEndports
Returns the list of all the end ports known to the Fabric Manager.
Return Value
An array of all the end ports.
Error
Error Code: 300— General SAN Service exception.
getEnclosures
Returns the list of all the enclosures known to the Fabric Manager.
Return Value
An array of enclosure objects.
Error
Error Code: 300— General SAN Service exception.
getEndPortByFWwn
Returns the end port based on FPort WWN.
Parameters
wwn—WWN of the FPort.
Return Value
Returns an array of end port based on FPort WWN. Returns null if there are no end ports associated with the FPort.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getEndPortByKey
Returns the end port based on Switch WWN.
Parameters
key—WWN of the node.
Return Value
Returns the end port based on Switch WWN. Returns null if there are no end ports associated with the Switch.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getEndPortAttachedToSw
Returns the end ports that are associated with a switch.
Parameters
key—IP address of the switch.
Return Value
Returns the end ports based on switch.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getEnclosureByName
Returns the enclosure based on the name.
Parameters
name—Name of the enclosure object.
Return Value
Returns the enclosure object..
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getEnclosureByKey
Returns the enclosure based on the name.
Parameters
name—Name of the enclosure object.
Return Value
Returns the enclosure object.
Error
Error Code: 300— General SAN Service exception .
Error code: 201—Invalid argument in Web Service exception.
getEnclosureByPWwn
Returns the enclosure that are associated with a physical WWN.
Parameters
wwn—Physical WWN of the switch.
Return Value
Returns the enclosure based on physical WWN.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
updateEnclosure
Update the enclosure with the value that is passed as parameter.
Parameters
value—Value to update the enclosure.
Return Value
None.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
updateEndportEnclosure
Update the end port enclosure with the value that is passed as parameter.
Parameters
endportKey—Value for the endportKey.
enclosureKey—Value for the enclosureKey.
Return Value
None.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getHosts
Returns the list of all the host enclosures known to Fabric Manager.
Return Value
Returns the list of all the host enclosures known to Fabric Manager.
Error
Error Code: 300— General SAN Service exception.
getHost
Returns the name of hosts in a VSAN.
Parameters
key—Name of the VSAN.
Return Value
Returns the name of the hosts in tthe specified VSAN.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getHostByFabric
Returns the name of hosts in a fabric.
ValidationException is thrown if any of the following situation occurs:
•If the argument passed is null.
•If the argument does not contain a valid key.
Parameters
key—Name of the fabric.
Return Value
Returns the name of the hosts in the specified VSAN.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getStorages
Returns the list of all the storage device enclosures known to Fabric Manager.
Return Value
An array of all the storage device enclosures known to Fabric Manager.
Error
Error Code: 300— General SAN Service exception.
getStorageByFabric
Returns the name of storage device enclosures in a fabric.
Parameters
key—Name of the fabric.
Return Value
Returns the name of the storages in the specified fabric.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getHostPorts
Returns the list of all the host end ports in a fabric.
Parameters
key—Name of the fabric.
Return Value
An array of all the host ports in a fabric.
Error
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
Error Codes
|
|
100 |
Authentication failure. |
101 |
Invalid credential. |
102 |
Invalid privilage. |
103 |
Invalid token. |
200 |
Web Service error. |
201 |
Invalid argument in Web Service function. |
202 |
Unreachable Web Service server. |
300 |
SAN service error. |
301 |
Invalid query key in SAN service |