Planning your API is important
I'm upgrading some code I wrote to talk to a new version of the Citrix NetScaler's API. The NetScaler's manuals (that's right, plural) weigh in at a combined 1114 pages so documentation isn't a problem and their implementation is a breeze using WSDL over SOAP. However, some of the core changes left me scratching my head. Case in point:
To get an object out of the cache in the previous version the method signature was:
getcacheobject(string $url, string $host, unsignedInt $port)
$url in this case is what is commonly referred to as the "path" in a standard URL; e.g. /en-US/index.html. That's simple enough to use, let's see what the new version has:
getcacheobject(string $url, unsignedLong $locator, string $host, unsignedInt $port [...]
$locator is an internal id for a cache object which is defintitely something I should be able to use to expire content, but what is it doing in the middle of my url+host pair? The error messages are happy to let me know that I can't pass both $url and $locator to the same call and if I pass $url I must pass $host. That means I will always have be passing a null value in either the first or second parameter.
And if you're thinking it's for consistency with other methods, think again. To flush an object we've got:
flushcacheobject(unsignedLong $locator, string $url, string $host, unsignedInt $port [...]
Moral of the story: planning and consistency makes happy programmers; particularly with an API.