The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The Cisco IP Interoperability and Collaboration System (IPICS) 4.5(x) application programming interface (API) provides a web services-based API that enables the management and control of various Cisco IPICS operations through programmatic interfaces and custom applications. The API includes a set of functions to control Cisco IPICS operations such as VTG creation, policy invocation, user management, and more.
This chapter introduces general concepts that relate to the web services API. It also explains how to generate a client stub by using the Eclipse integrated development environment (IDE), and explains options for executing API requests.
Before using the Cisco IPICS API web services functions, you must generate a client stub on the PC that is to be used for the API development (the developer workstation ). (A client stub is not used with the REST-based API functions.)
You can use a variety of tools to generate a client stub. The following sections describe how to generate the stub by using the Eclipse IDE.
Before you generate a web services client stub for the Cisco IPICS API, follow these steps to obtain and configure the Eclipse IDE:
Step 1 On the developer workstation, download the Eclipse IDE for Java Developers package from the Galileo (v 3.5.2) release of the Eclipse open-source IDE.
This IDE is available from the Eclipse website.
Step 2 On the developer workstation, download and extract Axis2 version 1.3 from the Apache website
Step 3 Take these actions to configure Axis2 runtime in the Eclipse IDE:
b. Choose Windows > Preferences .
c. In the Preferences window. expand Web Services .
e. Click Browse and, in the Browse to a Folder window, click the folder in which you extracted Axis2.
g. Click OK to exit the Preference window.
The following procedure describes how to use the Eclipse IDE to generate a client stub on a developer workstation. Before you perform this procedure, configure the Eclipse IDE on the developer workstation as described in the “Obtaining and Configuring the Eclipse IDE” section.
Step 1 Launch the Eclipse IDE and take these actions:
a. Choose File > New > Other... > Web Services > Web ServiceClient .
The Web Services Client window appears.
Step 2 In the Web Services Client window, take these actions:
a. In the service definition field, enter the following URL, where cisco_IPICS_server is the host name or IP address of your server:
http:// cisco_IPICS_server /ipics_server/services/IpicsWebService?wsdl
b. Make sure that the Client type field displays Java Proxy .
c. Click the Server: Tomcat version Server hyperlink.
The Client Environment Configuration window appears.
Step 3 In the Client Environment Configuration window, take these actions:
a. In the Server area, choose the server type that Eclipse uses when generating the stub (by default, the server type is Tomcat v X . X Server.
Step 4 In the Web Services Client window, take these actions, click the Web service runtime: Apache Axis hyperlink.
The Client Environment Configuration window appears.
Step 5 In the Client Environment Configuration window, take these actions:
a. Click Apache Axis2 in the Web service runtime area.
Step 6 In the Web Services Client window, take these actions, click the Client project hyperlink.
Step 7 In the Specify Client Project Settings window, take these actions:
a. In the Client project field, enter a name for the client project.
b. Make sure that the Client Project field displays Dynamic Web Project .
The Web Service Client window appears.
Step 8 In the Web Service Client window, click Finish .
The client stub is generated in a folder with the name that you specified in the Specify Client Project Settings window.
Each API service function (except the executePolicyForUser function) requires a valid session ID to access the API functions. To start a new web services session, the client code must call the startSession function and provide the login name and password that are used to authenticate the user who executes the API code. After authentication completes, the startSession method returns a unique SessionId value, which should be used when executing subsequent API methods in a web service session. To end a session, the API client code must call the endSession function, which invalidates the current SessionId and is important for security.
For additional information about using the API, see the “Function GuidelinesVV” section.
After you create API client code, follow these steps to execute it:
Step 1 Launch the Eclipse IDE and take these actions:
a. Click the name of the client file in the left panel of the window.
b. Choose Run > Run Configurations... .
The Run Configurations window appears.
Step 2 In the Run Configurations window, take these actions:
a. Right-click Java Application in the left panel of the window.
The following is an example of Cisco API client code for the web services functions. In this example:
– createVtg—Create a new VTG on the Cisco IPICS server and returns the ID of the VTG, activates VTG and returns list of all VTG's present in the system respectively.
– activateVTG—Activates the newly-created VTG.
– getAllVtgs—Retrieves a list of all VTGs that are present in Cisco IPICS.
The Cisco IPICS server and the Cisco IPICS API use SSL for secure communication between the server and client systems. The server uses a X.509 certificate (also called an SSL certificate ) to verify its identity when a client attempts to connect to the server.
By default, the Cisco IPICS server provides a self-signed certificate, which a client typically rejects. To prevent a client from rejecting this certificate, take one of the of the actions that Table 1-1 describes.
A client verifies its identity with a user name and password that are sent to the server by the client application.
The Cisco IPICS server logs all web service invocations. Entries include the date and time of the invocation, the API function that was used, and the status of the response.
This information is maintained in the Cisco IPICS log file. For more information about the log file, see Cisco IPICS Administration Guide .