It's great that you've released the functionality. And you asked, so I hope I don't come across too harsh. I'm looking at your examples, here for example:

http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercl...

To make a simple call with the Java example, you've managed to write 372 lines of code.

Three hundred and seventy two lines.

That's some bad code.

There's nothing I can point at and go, that, that's what's wrong, the whole thing just has a lot of code smells. The 'zZz's (what is that DIY escaping all about?). The multiple http calls that should have been abstracted into one function, but aren't. The over commenting. The api structure requiring you to do 3+ calls. The exponential call back time (this is not a good idea, have fun with weird bugs). That you've made your own json objects. That you've used PUT for a pretty tenuous reason. That you've put all the urls in some config file or something, so the code isn't particularly clear at what it's doing.

The ruby & javascript are more terse because those languages are, but they aren't that much better. It's often silly little things, like this:

    '/status?' + querystring.stringify({'jobid':jobid});

Could have been written simply as this:

    '/status?jobid=' + jobid;

There really is no good reason to use 'querystring.stringify' in that instance, it's not user input. The code's simply over-complicated.

The code reads like a sysadmin/amateur/uni professor's code, a scripter rather than a professional programmer's. It's like you don't have a senior dev on the team to cast an eye over it and get rid of the excesses.

The APIs themselves are not bad, as I mentioned there's the slightly tenuous PUT stuff, the only other annoyance I could see is that you'd have to ping it all the time to see if it's ready. I appreciate why, and you've made the right call in the callback vs ping, simply because so often when hacking setting up a callback would be hell.

It's better than a lot, like google or paypal, so it's not all bad.

NB: But now I just found this exploring github:

https://github.com/Watson-Explorer/wex-wdc-integration-sampl...

Which at first glance is better code than the examples on the site? Bit odd.