API Reference Guide for Cisco Application Networking Manager 5.2 and 5.1
Introduction to the Cisco ANM Web Services API
Downloads: This chapterpdf (PDF - 108.0KB) The complete bookPDF (PDF - 1.26MB) | Feedback

Introduction to the Cisco ANM Web Services API

Table Of Contents

Introduction to the Cisco ANM Web Services API

ANM Web Services Overview

Using the ANM Web Services

Required Software, Web Standards, and Supported Hardware

Enabling the Web Services Interface

Obtaining the Web Services Description Language File

Generating the Client Code to Invoke a Web Service

Calling an ANM Web Service and Posting a SOAP Request


Introduction to the Cisco ANM Web Services API


This chapter describes the Cisco ANM Web Services application programming interface (API), which provides a programmable interface for system developers to integrate with customized or third-party management applications.

This chapter contains the following sections:

ANM Web Services Overview

Obtaining the Web Services Description Language File

Using the ANM Web Services

ANM Web Services Overview

The ANM Web Services are a Web Service implementation, which is defined by the W3C standard as a software system designed to support interoperable machine-to-machine (client and server) interaction over the network. Client and server communication follows the Simple Object Access Protocol or Service Oriented Architecture Protocol (SOAP) standard. SOAP, which exchanges XML-based messages over the network using HTTP or HTTPS, is the foundation layer of the Web Service stack. It provides a basic messaging framework that allows more abstract layers to build on. SOAP encoding wraps XML headers and tags in a SOAP envelope.

ANM is a Java application that uses Java SE 6. Java SE 6 is a standard with Web Services support in the form of JSR 224, Java API for XML-Based Web Services (JAX-WS) 2.0. ANM makes use of Java SE 6 Web Services support to implement its Web Services-based NBI. Java SE 6 also supports JSR 181, Web Services Metadata for the Java Platform. JSR 181 makes it possible to develop web services. Additionally, Java SE 6 makes it extremely easy to publish a Java Web Service by using javax.xml ws.Endpoint of JAX-WS.

ANM provides the following Web Services to support the operation of the devices it manages, such as the Cisco Application Control Engine:

Operation Manager—Perform operational tasks such as:

Log in and out of ANM.

List objects such as virtual contexts, real servers, virtual servers, serverfarms, serverfarm real servers, VIP answers, and DNS rules.

Activate or susupend objects.

ApplicationTemplateManager—Perform the following tasks:

Manage application templates used to configure ACE devices.

Manage configuration checkpoints.

Obtain specific show command output.

For a complete list of the devices that the ANM Web Services support, see the "Required Software, Web Standards, and Supported Hardware" section.

Using the ANM Web Services

This section describes how to use the ANM Web Services. It contains the following topics:

Required Software, Web Standards, and Supported Hardware

Enabling the Web Services Interface

Obtaining the Web Services Description Language File

Generating the Client Code to Invoke a Web Service

Calling an ANM Web Service and Posting a SOAP Request

Required Software, Web Standards, and Supported Hardware

The ANM Web Services are supported in ANM software Version 4.1 and later. The API examples in this document require the following development environment:

Java SE 6


Note Java SE 6 is applicable only if the client code is java-based.


WSDL Support: 1.1

SOAP 1.1

The ANM Web Services API is supported on the following product types:

Cisco Application Control Engine (ACE) module and applicance

Cisco Content Services Switch (CSS)

Cisco Content Switching Module (CSM)

Cisco Content Switching Module with SSL (CSM-S)

Cisco Global Site Selector (GSS)

Enabling the Web Services Interface

ANM uses the following ports for Web Services:

http port: 8080

https port: 8443

After you have installed the ANM software, you can reconfigure ANM configuration properties, such as enabling HTTP(S) for Web Services. For information about enabling Web Services, see the "Changing ANM Configuration Property Values" section in the User Guide for the Cisco Application Networking Manager 5.2.

Obtaining the Web Services Description Language File

In the ANM Web Services, Web Services Description Language (WSDL) is used with SOAP and XML schemas to provide Web Services. WSDL is an XML-based service that describes the functionality offered by the Web Service and defines the actions, parameter names, input parameter data types, and return data types for the Web Service. When you connect to a Web Service through a web browser, you can read the WSDL file to determine which functions are available on the server. Any special data types that are used are embedded in the WSDL file in an XML schema. You can then call one of the functions listed in the WSDL file by sending a SOAP request message.

To obtain the WSDL file defined for a particular service in the ANM Web Services API implementation, submit a URL to the service with a ?wsdl suffix. For example, to retrieve the WSDL for the OperationManager service running on https://localhost:8443/anm/OperationManager, call the WSDL file by using the following URL: https://<host/ip>:8443/anm/OperationManager?wsdl. For more examples, see the "Generating the Client Code to Invoke a Web Service" section.

Generating the Client Code to Invoke a Web Service

To generate the client source code, follow these steps:


Step 1 Download the WSDL file from the server using the following WSDL URL formats:

OperationManager WSDL:

https://<host/ip>:8443/anm/OperationManager?wsdl

or

http://<host/ip>:8080/anm/OperationManager?wsdl

ApplicationTemplateManager WSDL:

https://<host/ip>:8443/anm/ApplicationTemplateManager?wsdl

or

http://<host/ip>:8080/anm/ApplicationTemplateManager?wsdl

where the host/ip value is the hostname or IP address of the ANM that has the service running.

Step 2 Save the file as either OperationManager.wsdl or ApplicationTemplateManager.wsdl, depending on which one you are downloading.

Step 3 Generate and compile the source code by using the wsimport command as follows:

wsimport -d <specify where to place generated output files> -s <specify where to place generated source files> {OperationManager.wsdl | ApplicationTemplateManager.wsdl}

The above command generates the java source code from the wsdl file and then compiles it and puts the class file in the same location where the source file .wsimport file is located in the dir $JAVA_HOME/bin.


Note This step is applicable only if the client code is a java-based code.



Calling an ANM Web Service and Posting a SOAP Request

To call a service, you connect to a particular ANM through a web browser by using a service URL that contains the IP address or hostname of the ANM and the name of the particular service (such as OperationManager). For example, https://<host/ip>:8443/anm/OperationManager?wsdl is the service URL for the OperationManager Web Service. You use the same format to call the ApplicationTemplateManager Web Service.

By default, ANM 5.1 supports up to 10 concurrent sessions for Web Services (see the "Modifying the Number of Concurrent Sessions Allowed" section).

Next, you must post a SOAP request written in a XML format to retrieve the information. The request calls for a particular action (such as login) and the input parameter content when required. The ANM responds with a SOAP envelope that contains the answer in an XML format. The response contains the output values for this action.

Example Request

The following example shows an XML-formatted SOAP request to perform the login action. There are no input parameters for this particular action.

<?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:Body>
  <login
    xmlns="http://anm.cisco.com">
   <user
    xmlns="">admin</user>
   <password xmlns="">admin</password>
  </login>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
 
   

Example Response

The following example shows the XML response to the login request. The response contains output values such as the SessionToken.

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope
   xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
  <ns2:loginResponse
    xmlns:ns2="http://anm.cisco.com">
   <SessionToken xmlns="">
    <sid>5546099606143734326</sid>
   </SessionToken>
  </ns2:loginResponse>
 </S:Body>
</S:Envelope>