I’m going through this at the moment as we’re adding an API to our research website.
The things I’ve learnt so far are:
- start with what you know - you already have the fundamentals of an API in your current URL’s - build on that. this is especially the case if you have ben RESTful
- RoR makes it easier - especially the XML and JSON handling in recent RoR versions
- rudimentary security is already in place in you current web app - but think about your authentication system. E.g. AuthLogic makes it real easy to use HTTP-Basic and extends well for other authentication systems
- you will need to extend the API to explicitly expose resources you don’t currently. e.g if you have options lists in web forms, you’ll need to expose those items via the API for clients to use
- you’ll need to tighten up your controllers and models, e.g. use attr_accessible and attr_protected properly so only the items you want exposed are exposed
- make sure that the important stuff is in the models - the controllers should just be there to set things out to the user (especially important if your API and web URLs are not the same to keep things DRY)
- an API is a contract - testing is pretty much mandatory to ensure the contract is and stays good
- document thoroughly! RDoc is your friend here
There are some design issues that need to be thought about - such as do you have your API the same as your regular RESTful URI’s? Whilst this is the easiest option, does it force you to match the API too closely to your website? what if you want/need to change things later on? Would it be better to have an explicit (and versionable) API URI structure?
Hmm… maybe I need to go write this all down somewhere :)