Generally speaking, Cisco collaboration products make use of one of the two most prevelant web services types, REST and SOAP. Each one has its advantages which we will discuss. In this section we will discuss SOAP and cover REST in later sections. Most of the Cisco Unified Communications Manager (CUCM) APIs (Administrative XML (AXL), UC Manager Serviceability (SXML), Platform Administrative Web Services (PAWS), etc) are exposed via SOAP-based XML Web Services, which conform to the Simple Object Access Protocol (SOAP) Specification 1.1 and the Web Services Description Language (WSDL) Specification 1.1. SOAP provides an XML-based communication protocol and encoding format for communication.

If you are not familiar with XML, it stands for eXtensible Markup Language and is a markup language that defines some relatively simple rules for encoding data. It was primarily designed to transmit and receive structured data in a well-defined format both systems can understand. In it's most basic form, XML defines tags which are enclosed in angle brackets (<>) and these tags surround the data described by the tag. Tags can form a hierarchy with tags inside of other tags. For example, to define a basic phone device, you might say that a phone device needs three parameters, a name, a description, and a phone number. To describe such a phone using XML, you would define the following structure:

Notice how for each tag, there is a corresponding end tag that includes a forward slash (/ before the tag name).

The names of the tags can, in theory, be any arbitrary string. In order for two devices using XML to agree upon what tags should be present and what type of data is expected between those tags, an XML schema is defined. An XML schema describes in painstaking detail not only the names of the tags, but also what order they should appear, what kind of data can be enclosed between the tags (for example a string, an integer, or some other sequence of tags), whether specific tags are mandatory, or if a particular tag can repeat more than once. Let's take a look at one of the simpler objects that can be configured on CUCM, a Partition. The following is a piece of the schema definition for a partition (called a RoutePartition in the API):

You can see that the definition of a Partition includes a name, description, timeScheduleIdName, and timeZone. The type field tells you what kind of data is in that field. The values that are a string are self-explanatory, but what is a XFkType or XTimeZone? To determine what these custom types are, you must find them in the schema definition, as they have their own set of rules. You will find that there will be many references to other parts of a schema and those other parts can further reference other parts.

XML schemas define how to describe an object or API call using XML. For example, you can describe a phone or a partition by following an XML schema. In order to perform transactions using these objects, you need something like SOAP which describes how to send requests and receive responses using XML messages.

The following diagram shows you the structure of a SOAP message:

What does this look like when encoded in XML?

The SOAP message above is a very basic request for the CUCM version. You can see that the getCCMVersion request has no parameters. The SOAP standard describes the above structure for a SOAP message. If you are thinking to yourself that this is getting complicated, you can relax. We are showing you what is happening behind the scenes, but as you will see shortly, there are many tools that will abstract this structure from you so that you don't have to deal with it.

If an XML schema describes the messages and objects that can be defined using XML, then how do you know what types of requests you are allowed to make, what types of data those requests require, and what type of response you expect to receive? This is where the Web Services Description Language (WSDL) comes into play. A WSDL file (along with associated XML schema files, that usually have the .xsd extension) can be used to fully describe the capabilities of a SOAP API.

The WSDL, in conjunction with the XML schema, can be thought of as a method signature for the web service. With it, you will know everything the web service can support, including Request and Response data types for all available methods.

A WSDL file defines four pieces of data:

1. Publicly available methods; interface description, formats
2. Data type information for requests and responses
3. Binding; which transport protocol to use
4. Address information – where to find the service

CUCM provides a WSDL file for each of the SOAP-based APIs it supports. When trying to utilize these SOAP based APIs, interpreting the WSDL files can be a daunting task. Fortunately, there are tools to read WSDL files and then make the SOAP API service methods available easily. The eventual goal is to leverage a programing language such as Python to interface with the various SOAP API's, but it helps to manually explore the API using a visual tool that can understand the WSDL file. One of these tools is SoapUI which has been installed on your workstation.

The first API you will explore is the Administrative XML Layer (AXL) API. The AXL API is a provisioning API for CUCM described in much greater detail in the next section. AXL essentially allows you to configure anything that you would be able to configure from the CUCM Admin web page.

Step 1 - Download the Cisco AXL Toolkit

The WSDL and XML schema files for the AXL API are published on the CUCM server itself, as part of the Cisco AXL Toolkit plugin. You will need these for SoapUI to be able to interact CUCM's AXL web service.

1. Access your CUCM server at: https://cucm1a.pod6.col.lab
2. Login in with username admin and password C1sco.123
3. Navigate to Application → Plugins and click Find
4. Next to Cisco AXL Toolkit, click Download. The file axlsqltoolkit.zip is downloaded.
5. From your Downloads folder, extract this downloaded file (right-click Extract All...) to the default location (should be in the Downloads\axlsqltoolkit folder)
6. Once extracted, in the schema folder you will notice there are a number of folders. These are for various older CUCM versions. For this lab, we are interested in current. That folder contains the current CUCM's AXL WSDL (AXLAPI.wsdl) and schema (.xsd) files.

Step 2 - Start SoapUI

Now you can load this WSDL into SoapUI, get things configured, and start sending queries. Follow these steps to load the WSDL into SoapUI.

1. From the Desktop of your laptop, launch the SoapUI application.
2. Close any open Endpoint Explorer or other windows that may show up when launching SoapUI.
3. Click File → New SOAP Project
   

4. For the Project Name enter UCMSOAP
5. Below that field, for the Initial WSDL file, click Browse. Navigate to your current AXL WSDL file extracted earlier:
   Click on button the get to the Desktop, then enter or navigate to the location of the file C:\Users\student1\Downloads\axlsqltoolkit\schema\current\AXLAPI.wsdl
6. Make sure Create sample requests for all operations is checked and click Ok to open the new project.

Step 3 - Run an AXL Request from SoapUI

Once the API is loaded, you must set some of the default parameters, specifically the CUCM hostname or IP address and the credentials so that they don't have to be re-entered for every query.

1. In SoapUI, in the Navigator pane on the left, you'll see the new project folder named UCMSOAP and the AXLAPIBinding object. Right-click on the AXLAPIBinding and click Show Interface Viewer (same as double-clicking or pressing Enter).
   

2. In the AXLAPIBinding properties, select the Service Endpoints tab.
   

3. You'll notice the Endpoint is set to https://CCMSERVERNAME:8443/axl/ (with blank username and password). Double-click on CCMSERVERNAME so it can be edited.
4. Replace it with the hostname of your CUCM: cucm1a.pod6.col.lab so the complete endpoint URL is https://cucm1a.pod6.col.lab:8443/axl/ and press Enter
5. Double-click on the Username field and enter admin . Be sure to press Enter for the field to be saved.
6. Double-click on the Password field and enter C1sco.123 .
7. Be sure to press Enter to save the value.
8. Close the AXLAPIBinding window by clicking the X in the right of its blue title bar .

SoapUI is now all set up for issuing queries. When you opened the WSDL file in SoapUI, SoapUI parsed the contents of the file in addition to the XML schema files that are referenced in the WSDL to provide you with a list of all the actions you can take using the AXL API. You will notice that the Navigator pane on the left contains a list of all the AXL API methods available in the API. Just as all these methods are now available to you at the click of a button, you will see later how certain libraries can perform a similar action in Python to read the WSDL file and make all of these methods available to you programmatically. To experience your first AXL SOAP API call, follow the steps below:

1. Scroll down to find the getCCMVersion method.
2. Expand (usually the + sign) the getCCMVersion operation, so you can see Request 1
3. Double-click on Request 1 to open it. Note: You can always right click on a SOAP operation/service and create a New request with the default SOAP XML payload.
   

4. You should see your CUCM server listed in the URL at top. The XML request will look like this:
5. Click the green "play" button to send this request. Observe that the response is filled in at right. In this case, it indicates an error
6. The reason for this error is you supplied the optional processNodeName with a name of ?. When a new request is created for an operation in SoapUI, all available options are presented, so there are often many that either need to be removed or filled in with valid data (instead of the default ? placeholder).
7. Remove the processNodeName line and the comment above it or just copy the text below and replace the entire request with this:
8. Click Run and observe the response which should contain:

You have successfully sent an AXL/SOAP request to CUCM and received a valid response. This request was fairly basic as you did not have to provide any parameters in the request. Even with only one piece of information in the response, the version of CUCM, the response seems fairly complex. Having to manually parse and extract the data from the XML-based response may seem daunting. You will see later when you perform similar actions using Python that the SOAP library you will be using will greatly simplify the process of extracting the data from the response.

In the next section, you will explore the AXL API in more detail and construct some more complex requests.