So.. we’re working on a iPhone app. Ravelers, just like the users of most other sites, are clamoring for one. It’s not just that, though - we think that Ravelry will make a great mobile app and that being on the iPhone will be a really good thing for us.
Adding a full featured API to the site has been a really good exercise. It’s really helped me to improve code quality and tie up loose ends and I’m glad that the iPhone has finally sparked the creation of an API for Ravelry.
I was surprised to find that the software support for API needs is lacking in places. Here are some of the missing or ill-fitting pieces that I’ve run into so far:
Routes, controllers and actions
Rails gives us formats and :respond_to. Rails 3 makes it even better…. but I don’t like it. I don’t like mixing my API actions up with my non-API actions because the logic is never the same except for the simplest methods. For now, I’m just manually adding routes that send my API (JSON) requests to X_with_api actions. Hopefully some sort of pattern will emerge and an idea will sprout… or maybe I’ll see the error of my ways.
Documentation
I couldn’t find any way to generate pretty API documentation from simple structured text or code comments. There are so many people creating and documenting HTTP APIs that I was a little surprised by this. For now, I made up a code commenting convention and borrowed heavily from YARD. I could try to figure out a way to get YARD to parse the stuff but I suspect I’ll end up hacking up a simpler parser that generates HTML documentation.
I like that this combined with the above results in methods dedicated to each API call with code comments that describe the HTTP parameters and JSON output. Add in a little setup code and some sample parameters and I could probably create tests from this.
Rendering the Results
For now, I’m only providing JSON. When I first started out, I was wishing for some XML::Builder/rxml like thing that I could use to write templates that generated JSON. My wish has since been granted by the Tequila RailsRumble project but I’m glad that I ended up going in a different direction.
I’m using my own take on the serialize_with_options plugin. This allows me to set up multiple serialization “styles” (for example, I might have “compact” and “normal” - for search results vs retrieving a full object) and declare what attributes, method return values, and associated objects to include. I’m liking this approach so far: it means that all of my API data has to be in a model as a method or attribute which will be easier to maintain. It also results in a little DSL that I should be able to use to generate API documentation that describes the return values.
That’s what I’ve got so far. It’s my first time building such a full-featured API and it feels a little like I’m inventing things that I shouldn’t have to invent. At least what I’ve got so far seems like it will be easy for me to maintain. I’m just getting started, so who knows where I’ll be by the end.
PS Ravelers - I know that you are probably excited to hear about the iPhone thing 
Check out this thread for more information: http://www.ravelry.com/discuss/for-the-love-of-ravelry/601827/76-100#82
Comments (11)
Is there an easy way to serialize JSON in the iPhone SDK? How do you feel about networking in general?
I’ve tried several times to jump in to it, but Objective-C seems to take ten steps backward from modern languages and I just can’t get in to it.
Not directly in the SDK that I’m aware of. At Quickoffice, we use the open source JSON parser in Google’s open source code base to parse and generate JSON. It works with NSDictionary and NSArray classes and handles most common basic types (like NSNumber) pretty well.
http://code.google.com/p/json-framework/
Good luck with your iPhone app development and launch! If you open the API to third-party developers I’d definitely be interested in checking it out.
Best, Dave KnitBuddy developer
Argh. Gonna hafta get an iPhone now if I can get a Rav app for it. Damn you codemonkey!!
What I’ve been doing lately for API calls is to put a Rack application in front of the Rails stack, usually at something like /api/ and doing all the API calls through those.
i think rack (sometimes with sinatra) is better (and certainly faster) at handling those types of requests.
an alternative method is to put a sinatra metal application, and bypass everything but the router for that, and use sinatra’s routing handlers for it, inside of the metal app
Ooo…I Googled “ravelry iphone app” and stumbled upon your page! Please tell me it’s true? I’m dying for a knitting app that pulls my info from Ravelry and let’s me keep track of my projects in progress (count stitches, rows, repeats, like KnitBuddy).
So excited for this!
KelleBelle,
Get an iPod Touch instead! What AT&T’s got going on with the iPhone is highway robbery–$80/mo for service! Sure, the iPhone is great if you want to be able to get directions and navigate while on the road, but I love my iPod Touch for everything else as I can get WiFi just about anywhere I go. For voice service I still use my dumb old feature-poor clamshell–it does the trick and is a helluva lot cheaper since I don’t talk all that much and use prepaid.
Just about any iPhone app can be installed on the iPod touch as well, as long as it doesn’t require a microphone or 3G. Can’t wait for the Ravelry app for my iPod touch!
Would you ever consider an android app as well? I’m a Mac person, but need to be on Verizon, so I’m crossing my fingers!
Seconding the Android app. I wish that apps were more portable. Apparently there are programming systems where you can write the code once and then compile both for iPhone and Android, but it must be kludgy since it never seems to happen.
How do we become a beta tester for the app? So glad to hear you are working on this!