Today, I was at Hack Dev days in Vancouver, B.C. and enjoyed the group and the presentations. Two recent Uni-grads and I teamed up and proceeded to define a project and work away for most of the day. We were using the TinEye.com API, specifically a collection of 10 million images from Flickr that they have in one of their libraries. We decided to create a Chrome Extension on the API (one of the other dev’s had done one of these recently).
It’s been 16 months since I have done any serious JavaScript/Ajax stuff, and that was (in hind-sight) unfortunately against the website where the pages were hosted…
The code that consumed most of the day…
The code below should have been up and working in 15 minutes…
<script type="text/javascript"> var ApiUrl = 'http://piximilar-rw.hackdays.tineye.com/rest/' function myData() { var fd = new FormData(); fd.append("method", "color_search"); fd.append("colors[0]", "#FFFFFF"); fd.append("colors[1]", "#F080C0"); fd.append("weights[0]", "90"); fd.append("weights[1]", "10"); fd.append("color_format", "hex"); fd.append("limit", "10"); return fd; } var data = null; function testcall() { var xhr = new XMLHttpRequest(); xhr.open("POST", ApiUrl); xhr.onload = function () { data = JSON.parse(xhr.responseText); } xhr.onerror = function () { alert(xhr.status); } xhr.send(myData()) } </script>
The problem was that the status was a zero(0) with no status message. Googling XMLHttpRequest and zero status code found many pages describing a similar issue but no clear explanation (or solution). I installed the latest version of Fiddler Web Debugger, and saw that the call went off fine, and that the service returned the appropriate JSON fine.
So the call to the API was being correctly done, results were coming back but with a bizarre status code of zero. Asking around the local HACK developers and no one had an answer…. So it was off trying to find a solution, including trying $.ajax () – which provided less information, overriding mime types, changing “POST” to various other REST verbs (GET was rejected by the API)… the typical systematic trying every variation that came to mind. My colleagues were also encountering problems that they could not identify the cause ….
Looking at TinEye.com API documentation did not help, it was centric around the use of cURL with no examples that could be easily copied. They supplied some sample pages using FORMS, but our intent was calling if from JavaScript, so it was not particularly helpful…
Well, finally the light went on (I was the one that realize the issue), we were trying to do cross domain POSTs. It turned out that their obtuse problems were the same issue.
In hind-sight, the waste of time could have been avoided if:
- There was a statusText message that went with the zero status code (i.e. “Security violation – cross domain post”), or
- The .send() raised an error message….
- Seeing the data coming back in Fiddler, lead me down the wrong path – the API appear to be working correctly…
- The TinEye.com documentation had reminded the reader about the cross-domain posting issue
- Ideally, the documentation would have sample code on how to create the needed component on your own server in all of the common languages. Having the code ready to cut-and-paste would have improved adoption
- Personally, I would love to see firms providing API’s contract out to a seasoned technical developer engineer (what I use to be called at Microsoft) who is good at:
- Technical writing
- Creating non-trivial engineering code examples that goes the “extra mile” (resulting in faster adoption of the API).
- Anticipating how novice developers are likely to proceed and making them successful!
- The Facebook API is THE classic example of how not to do API documentation.
- I (or my fellow hacks) had bumped up against the cross-domain API post issues recently.
That’s it for today’s RANT…
Posts
