Debugging API requests with HTTP Client
Zach Waugh •
I received quite a few comments on my How to use JSON in Cocoa/Objective-C post with some confusion related to the response from API calls. I thought it might help to show an example of the steps you'd take if you wanted to integrate the Twitter public timeline (or any other API) into your app or site. For doing any sort of HTTP/API request analysis, I first turn to HTTP Client.
HTTP Client by Todd Ditchendorf (creator of Fluid) has quickly become an indispensable tool for me when writing code that interacts with RESTful API web services. For building the request, HTTP Client allows to you use any of the HTTP verbs (GET, POST, PUT, DELETE, etc) as well as setting custom headers, body, and use basic authentication. The response view will show you all the headers and the raw request body. If you're still using cURL, it's time for an upgrade.
Typically, the biggest problem with using APIs is poor documentation. Even when the request docs are pretty good, the response docs often fall short. Either they don't document the response at all, only document a portion of it, or only show it in one format. So my first step in implementing some API code is looking at the docs, and seeing how the request is formed. Twitter has a simple API, and pretty good documentation, so it's easy to figure out how to get the public timeline as JSON on this page http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-public_timeline. The URL for this request is just "http://twitter.com/statuses/public_timeline.json" and the HTTP method is "GET".
The next step is firing up HTTP Client and making the request to see what it looks like (see screenshot to the right). Twitter is a simple case where you shouldn't have trouble, but for more complex APIs with a lot of options (like the Google Analytics API), it might take a bit of trial and error to get the exact data you're after. It's much quicker to iterate in HTTP Client to get your requests working right than to try to do so in code. This will allow you to get your request formatted correctly, and find any problems, like authentication errors or unexpected redirects, right away.
Once I have the correct request, the final step is to look at the structure of the response so I know how to parse it. I prefer to use JSON whenever possible, so it's mostly seeing what is an array, what is an object, and how things are nested. HTTP Client seems to do a pretty good job with syntax highlighting of XML and HTML responses that make them nice and readable, but unfortunately not with JSON. A quick solution is to copy the response, paste it into TextMate, set the document as JSON, and use JSON-> Reformat Document. (You'll need the JSON bundle to do that) That will give you a nice, readable view of the structure.
In the screenshot to the right, you can see the JSON response of the public Twitter timeline. By looking at the response, I can immediately see first off, that the main structure is an array. The elements of the array are status objects and each status object contains a user object. Without looking at the formatted response first, it might not be obvious that the user is a nested object of the status.
That's it. Now I know exactly how the request and response are formatted, and I can easily write the implementation code without any surprises. It seems like a bit of work, but it's all of 5 minutes when you're familiar with the process, and is much faster than trying to locate a bug in code that's really due to a malformed request or unexpected response structure.