TheAXL PhilosophyandPurpose

We, as programmers, often look at an API with wild dreams about building dazzling user-facing applications that inspire jaw-dropping amazement.That's just how we're built. And the AXL API has the power to let you do that.

One word... DON'T.

AXL is not an API for user-facing applications. It's an administrationandconfiguration API. You don't want to push an end-user application built on AXL to 1,000 users. And if you do, you're going to have a bad time.

Think of AXL as a programmatic way to perform web GUI administration and configuration tasks. For example, in the web GUI, you add an end user this way.

1. SelecttheUser Managementmenu
2. Select End User
3. Click on+Add New
4. Fill out the form
5. Save.

Now, programming that might seem silly and more work than using the web GUI. But think of it this way. You have a text file with a list of names, email addresses, phone numbers, assigned company phone extension and other personal data of new employees. Now you can write an application that reads the file and creates and configures an end-user account for each of the persons and creates and configures lines and phones entries for them. That's automating an administration and configuration task in a way that makes your life as an administrator easier.

The Basics

AXL is a SOAP-based API. There's no REST for the wicked here.

The most often used AXL APIs fall into the following groups:

1. addSomething (e.g., add a phone)
2. getSomething (e.g., get a phone's info and settings)
3. updateSomething (e.g., change a phone's info and settings)
4. applySomething (e.g., apply the changes you made for the phone)
5. removeSomething (e.g., remove a phone)
6. listSomething (e.g., list all phones)

There are a few other AXL APIs not in those groups that you'll need at times, but those are the most frequently used operations.

Getting Started: Preparation

The best way to get familiar with AXL is to use a free, open-source tool calledSoapUI. SoapUImakes it easy to experiment with the AXL API. But first, you need to download the files you'll use withSoapUI.

Log into Call Manager as an administrator. Under theApplicationmenu, selectPlugins.

Click theFindbutton (not shown in this screen shot). The first item is the Cisco AXL Toolkit. Click onDownloadand save it somewhere.

The saved file should look like this:

Open thezip file to see its contents

Open the schemadirectory.

Pick the version of Call Manager you are using. In this sample, we'll pickcurrent.

Copy the three files above to a working directory. I choseC:\SOAP.

Download and install the open-sourceSoapUIfrom this page. | | |  You're done with preparation. Now, it's time to create an AXL project to play with the API.

Set Up a SoapUI AXL Project

Click on theFile menu and chooseNew SOAP Project.

Pick a name for your project. Set theInitial WSDLto point to theAXLAPI.wsdlfile you saved to a working directory earlier. ClickOK.

In the left column, you should see this (assuming you used the nameNew AXL Test, otherwise look for the name you chose).

Right click onAXLAPIBindingand selectShow Interface Viewer. You should see this Dialog Box.

Click on the Service Endpointstab and you'll see where you can enter information for AXLAPI binding.

Type what you see in theEndpointfield, except point toyourserver where it saysYOURSERVER. Assuming it's safe for your work environment to do, enter your Administrator username and password in the appropriate fields. You can create an Administrator account in Call Manager specifically for use with the AXL API, or you can use your primary Administrator account.

You can close this dialog box now.

Now let's play with one of the requests. In the left column, findlistPhoneand click on its plus sign. Then double-click onRequest 1. You should see all the XML for this request pop up in a new dialog.

The listPhonerequest has a few potential hangups that are good to learn how to avoid. AnylistSomethingrequest is going to return, well, a list of things. Scroll down to the bottom of the request XML and you'll see these options. These give you the option to skip a number of results, or define the starting point. We don't want to mess with those options right now, so select them and delete them.

At the top, look for what I have selected here, select it and delete it. This attribute can be useful, and you don't always have to delete it, but in this case, you'll need to remove the 'sequence="?"' for the request to work properly.

There's one more thing. Get rid of what you see selected in this screen shot. Select it and delete it.

There are way too many values to specify, so let's chop down the request to look like this. Make sure to put a percent sign in the <name></name> tag. This is a wild card, which means it will list ALL the phones. You want to start simple, so this is a simplifiedlistPhoneoperation.

Now's the time to try it out. Click on the green "run" icon in the upper left. You should see the right side of the request change to this:

This is an unfortunate bug in the current version ofSoapUI. It should show you the XML response by default, but it instead shows you raw information. Until the app is fixed, you'll have to click on the upper left XML tab to view the response.

The response might look something like this:

With that, you now have enough basic knowledge to experiment with any of the AXL APIs. Hey now, you're an all-star, get your game on, go play.

Once you are familiar with how the API works, try programming with the API:

• Here's a Python AXL Zeep learning lab.
• Here's a short tutorial on Python AXL and Zeep.

Programming Tip

And if you really want to run with the big boys, here's a tip for running multiple AXL request sequentially. Every time you make an AXL request, Call Manager launches a Tomcat session. When you make many requests in a row, Call Manager will launch multiple Tomcat sessions, which use up CPU and RAM.

Here's a way around that. At the bottom of the response, open up the headers and you'll see a cookie named JSESSIONID and its value.

If you set the JSESSIONID cookie and use the same value for your next AXL request, Call Manager will re-use the Tomcat session instead of launching a new one.

What to Avoid and Common Mistakes

Many requests have a list of optional search parameter tags, commonly<name> and <uuid>. You will usually have to choose one and delete the others.

As logical as it may seem, you can't perform agetPhone, change some values, and then copy and paste the modified XML into anupdatePhonerequest.getPhone and updatePhoneXML tags are not mirror images.

Be careful when using APIs that give you direct access to the Call Manager database, likeexecuteSqlQuery. Complicated joins may be clever, but they can also suck up CPU and memory the size of a spy balloon, and that eats into the performance of every other operation.

Resources

• Open-Source SoapUI
• Python AXL Zeep Learning Lab
• Python AXL and Zeep

We'd love to hear what you think.
Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

LinkedIn | Twitter @CiscoDevNet | Facebook | YouTube Channel