The AXL Philosophy and Purpose
We, as programmers, typically take a look at an API with wild goals about constructing dazzling user-facing functions that encourage jaw-dropping amazement. That’s simply how we’re constructed. And the AXL API has the facility to allow you to try this.
One phrase… DON’T.
AXL shouldn’t be an API for user-facing functions. It’s an administration and configuration API. You don’t need to push an end-user utility constructed on AXL to 1,000 customers. And if you happen to do, you’re going to have a foul time.
Think of AXL as a programmatic strategy to carry out internet GUI administration and configuration duties. For instance, within the internet GUI, you add an finish consumer this manner.
- Select the User Management menu
- Select End User
- Click on +Add New
- Fill out the shape
- Save.
Now, programming that may appear foolish and extra work than utilizing the online GUI. But consider it this manner. You have a textual content file with an inventory of names, e-mail addresses, cellphone numbers, assigned firm cellphone extension and different private information of recent workers. Now you may write an utility that reads the file and creates and configures an end-user account for every of the individuals and creates and configures traces and telephones entries for them. That’s automating an administration and configuration job in a method that makes your life as an administrator simpler.
The Basics
AXL is a SOAP-based API. There’s no REST for the depraved right here.
The most frequently used AXL APIs fall into the next teams:
- addSomething (e.g., add a cellphone)
- getSomething (e.g., get a cellphone’s data and settings)
- updateSomething (e.g., change a cellphone’s data and settings)
- applySomething (e.g., apply the modifications you made for the cellphone)
- removeSomething (e.g., take away a cellphone)
- listSomething (e.g., listing all telephones)
There are a couple of different AXL APIs not in these teams that you simply’ll want at instances, however these are probably the most continuously used operations.
Getting Started: Preparation
The finest strategy to get conversant in AXL is to make use of a free, open-source instrument referred to as SoapUI. SoapUI makes it simple to experiment with the AXL API. But first, you could obtain the information you’ll use with SoapUI.
Log into Call Manager as an administrator. Under the Application menu, choose Plugins.
Click the Find button (not proven on this display shot). The first merchandise is the Cisco AXL Toolkit. Click on Download and reserve it someplace.
The saved file ought to appear like this:
Open the zip file to see its contents
Open the schema listing.
Pick the model of Call Manager you’re utilizing. In this pattern, we’ll decide present.
Copy the three information above to a working listing. I selected C:SOAP.
Download and set up the open-source SoapUI from this web page. You’re accomplished with preparation. Now, it’s time to create an AXL venture to play with the API.
Set Up a SoapUI AXL Project
Click on the File menu and select New SOAP Project.
Pick a reputation in your venture. Set the Initial WSDL to level to the AXLAPI.wsdl file you saved to a working listing earlier. Click OK.
In the left column, it is best to see this (assuming you used the title New AXL Test, in any other case search for the title you selected).
Right click on on AXLAPIBinding and choose Show Interface Viewer. You ought to see this Dialog Box.
Click on the Service Endpoints tab and also you’ll see the place you may enter info for AXLAPI binding.
Type what you see within the Endpoint area, besides level to your server the place it says YOURSERVER. Assuming it’s protected in your work atmosphere to do, enter your Administrator username and password within the acceptable fields. You can create an Administrator account in Call Manager particularly to be used with the AXL API, or you should utilize your major Administrator account.
You can shut this dialog field now.
Now let’s play with one of many requests. In the left column, discover listPhone and click on on its plus signal. Then double-click on Request 1. You ought to see all of the XML for this request pop up in a brand new dialog.
The listPhone request has a couple of potential hangups which are good to learn to keep away from. Any listSomething request goes to return, properly, an inventory of issues. Scroll right down to the underside of the request XML and also you’ll see these choices. These provide the choice to skip a lot of outcomes, or outline the place to begin. We don’t need to mess with these choices proper now, so choose them and delete them.
At the highest, search for what I’ve chosen right here, choose it and delete it. This attribute could be helpful, and also you don’t at all times should delete it, however on this case, you’ll have to take away the ‘sequence=”?”’ for the request to work correctly.
There’s another factor. Get rid of what you see chosen on this display shot. Select it and delete it.
There are method too many values to specify, so let’s chop down the request to appear like this. Make positive to place a % signal within the <title></title> tag. This is a wild card, which implies it would listing ALL the telephones. You need to begin easy, so this can be a simplified listPhone operation.
Now’s the time to attempt it out. Click on the inexperienced “run” icon within the higher left. You ought to see the fitting aspect of the request change to this:
This is an unlucky bug within the present model of SoapUI. It ought to present you the XML response by default, however it as an alternative reveals you uncooked info. Until the app is fastened, you’ll should click on on the higher left XML tab to view the response.
The response would possibly look one thing like this:
With that, you now have sufficient fundamental information to experiment with any of the AXL APIs. Hey now, you’re an all-star, get your recreation on, go play.
Once you’re conversant in how the API works, attempt programming with the API:
Programming Tip
And if you happen to actually need to run with the massive boys, right here’s a tip for working a number of 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 a number of Tomcat periods, which burn up CPU and RAM.
Here’s a method round that. At the underside of the response, open up the headers and also you’ll see a cookie named JSESSIONID and its worth.
If you set the JSESSIONID cookie and use the identical worth in your subsequent AXL request, Call Manager will re-use the Tomcat session as an alternative of launching a brand new one.
What to Avoid and Common Mistakes
Many requests have an inventory of non-compulsory search parameter tags, generally <title> and <uuid>. You will normally have to decide on one and delete the others.
As logical as it might appear, you may’t carry out a getPhone, change some values, after which copy and paste the modified XML into an updatePhone request. getPhone and updatePhone XML tags usually are not mirror photographs.
Be cautious when utilizing APIs that provide you with direct entry to the Call Manager database, like executeSqlQuery. Complicated joins could also be intelligent, however they’ll additionally suck up CPU and reminiscence the dimensions of a spy balloon, and that eats into the efficiency of each different operation.
Resources
We’d love to listen to what you assume.
Ask a query or go away a remark under.
And keep related with Cisco DevNet on social!
LinkedIn | Twitter @CiscoDevNet | Facebook | YouTube Channel
Share: