CallXML 2.0 Development Guide

| TOC

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Cache Manager API and Caching Exposed!

As you may very well know, caching is a critical piece in any Internet-reliant system. The Worldwide Web is a massive interconnection of moving parts, any of which can experience issues on a daily and ongoing basis. To help minimize failures and increase efficiency in this chaotic world, caching proxies act as intermediaries to help quell the chaos.

Let’s take a look at a basic definition of a caching proxy:

A proxy server can service requests without contacting the specified server by retrieving content saved from a previous request made by the same client or even other clients. This is called caching. Caching proxies keep local copies of frequently requested resources, allowing large organizations to significantly reduce their upstream bandwidth usage and cost, while significantly increasing performance.

As you can see from the definition, these "caching proxies" store previously retrieved information so a future request no longer has to traverse the full internet path to the "host server." Any subsequent request now hits the caching proxy, which simply says "Déjà vu! I have seen this file before; no worries, I will serve this content out of my cache".

In the Voxeo Network, these caching proxies are local (LAN/Intranet) fetches from the VoiceXML/CCXML/CallXML browsers issuing the request; thus, there is no need to fetch from the scary outside world (i.e., let’s just stay inside our comfy intranet). In this way, we are able to achieve much greater levels of performance and have mitigated our exposure to Internet based uncertainty. To provide a real world example and explain the benefits of caching, lets say your application starts with a 1mb introductory audio file. For each call we would be performing a fetch to your web server for this large file. This constant behavior would likely not be an issue for 1,5, maybe 10 concurrent calls, however how would this hold up with 100,500,10000 concurrent calls? This will certainly eat up unnecessary amounts of bandwidth under heavy load and cause possible delays or dead air for your callers. When proper caching is used though, we are able to offload all this bandwidth and resource strain off your network and onto the Voxeo network. We will perform the initial fetch, cache it, and all subsequent fetches will happen internal to our network.

At this point, you are probably thinking "great sign me up," and at the same time asking "how do I make this all work for me!" Well, it’s pretty easy and all you have to do is ensure that your web-server is passing the appropriate caching headers along with our requests.

To ensure I get down to the real goal of this document, we have some great documentation already prepared on caching and manipulation of the various headers here:

Caching Tutorial

At the time this article was written, we had yet to develop an API that allowed you the ability to control our caching proxies. With this Cache Manager tool, you can now SET and CLEAR our whole farm of caching proxies with ease!

Cache Manager API:

Allow me to introduce the Cache Manager API, a simple yet highly effective means to control caching at your desire. There are two distinct forms for utilizing this tool. One via our web-based GUI, and the other via a purely HTTP GET/POST driven API interface. Currently, both of these functions are only offered for Production customers. While you are in a development-only stage, it remains highly advisable to send no-cache headers (because you are constantly modifying documents). This will undoubtedly save you countless hours of hair pulling and stress.

"So, how do I use this? I am a production customer and this sounds great – show me the goods!!"

To get started, all it takes is a request to your friendly neighborhood Extreme Support Team to provide access. In order to do so, send us your accountID and the URL of the domain where the files you wish to have cached are stored and you are well on your way.

Nothing better than an example, so let’s see it – you send over two URLs of domains where you will store files to be managed with our Cache Manager API:

http://mywebserver.com/
http://subdomain.mywebserver.com

A Voxeo Support Administrator will provide access and you can now SET and CLEAR cache on fully qualified URLs from these domains. For example:

http://mywebserver.com/audio/myaudiofile.wav
http://subdomain.mywebserver.com/audio/myaudiofile.wav

Furthermore, since we provided the root domains, subdirectories can also be managed with ease:

http://mywebserver.com/www/audio/week1audio/123.wav
http://subdomain.mywebserver.com/audio/week2audio/123.wav

"Good, good, easy enough, but what does the interface look like? It must require a command line and extensive bash knowledge, right?!"

No way! It’s as easy as any other web form, located in your Tools and Downloads tab and you can set and clear up to 25 fully qualified URLs at once.

Using the GUI, which is pictured above, you can set/clear cache on up to 25 URLs at once:

In addition to the above easy-to-use web GUI, you can also access the cache manager API through an HTTP request.

Here is what a sample request would look like using the API – nothing complicated, just a simple http GET or POST request:

http://cachemanager-api.voxeo.net/caching/2.0/management?action=setcache&accountGUID=xxxxxxxx-C444-4D17-xxxxxx-17CE883881EE&url=the_actual_url

Using the API method, you can set/clear cache on one URL at a time. Of course, since you can issue GET/POST requests from a server-side, script-driven environment, you can now fire off these requests in an automated fashion and in mass quantity!

In addition, just as you get full verbose logging output when using the GUI such that the results of each individual proxy in the farm returns back its status, you also do so using the direct API, so don’t feel left out! In order to access this, you will need to tack on additional query string parameter,

verboseOutputYN=Y

So, a full string that would return the verbose output, would look like this:

http://cachemanager-api.voxeo.net/caching/2.0/management?action=setcache&accountGUID=xxxxxxxx-C444-4D17-xxxxxx-17CE883881EE&url=the_actual_url& verboseOutputYN=Y

"What about security, what prevents anybody from sending this request and clearing your cache servers of my files without my knowledge?"

I am glad you asked, each account has a specific accountGUID that is a unique string used for identification purposes. In this, we are able to keep access to your account caching available only to you and no one else, don’t you feel special.

"Good deal., I got this down to a science, but why do I care to manage the setting and clearing of files in your cache to such a fine grain? Can’t I just rely on my caching headers taking care of it all?"

In order to understand why, we need to take a brief detour into how our proxies honor caching headers in terms of max-age or the "expires" date being sent. While you can feasibly send in a HTTP caching header that says "cache me for 10 years," we won’t fully honor this rather extreme value. Our caching proxies will take either 20% or 7 days of this "max-age" value, which ever comes sooner. When this value is met, our proxies will wonder, "Hmmm, it is possible this file has changed, let’s go and perform a ‘refresh’ fetch." This fetch consists of going to the hosting source and grabbing the file headers to see if the "last-modified" date matches what we have on record. If it does, then we update, and we are golden for another 20% or 7 days. If the "last-modified" date has changed, this file is assumed to be different than what we have on record and a full fetch of the file occurs. After this, we are again "good to go" from the caching perspective for another 20% or 7 days. There are additional reasons beyond the above rules where a file might be "purged" from cache. As these files are ultimately stored in memory and or disk on these servers, there are size constraints to these mediums as well as specific server maintenance events that might cause a file to no longer be in cache and a full fetch to your web server occurring.

To ensure files are always "fresh" and these "refresh" fetches never occur, it is recommended that you employ a pre-caching regimen, especially for high volume inbound and mass notification outbound applications. This regimen will consist of repopulating the cache with a SET command through our Cache Manager before each call blast. When you issue this SET command, you can be sure all of our proxies have a fresh copy of the file, and there should be no reason for a request to hit your web server other than failures on our entire proxy farm. You can imagine this would be a saving grace if your application is driving five or ten thousand concurrent calls, and each one has to perform constant fetches to your web server for content.

In addition to this best practice, the Cache Manager allows you to manage the entire proxy farm (multiple server instances) in one fell swoop! This becomes a great asset for managing your application content, as any delay or failures to fetch content seriously hamper telephony applications.

I hope you find this information helpful when deploying applications on the Voxeo platform. Caching is a very important part of a healthy application and the ability to control the caching proxies storing content is ultimately advantageous. At the end of this document, you should be an all-knowing Jedi Master of Voxeo caching proxies, and best understand the power you wield with the Cache Manager tool. If for any reason any part of this document is unclear, our 24x7x365 Extreme Support team is always happy to assist.

~Extreme Support
Open a Support Ticket!

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Caching Techniques

| TOC

| CallXML 3.0 Porting guide