How should I create a REST API using Rails 3.0?

Question

I can't seem to find much information on the web about the different approaches to building a REST API in Rails; so I kinda have two questions:

1. Can someone point me to some articles that show the pros/cons of the different approaches?
2. Would you please share your thoughts on the pros/cons of the following approaches?

 

Proposed Approaches

 

1. Use the standard controllers to return XML when a users adds .xml to the end of the URL

   Pros:

   • This is built-in to Rails and very easy to use
   • Follows the same resource-based approach that Rails has, so it will be easy for existing users to understand/remember

   Cons:

   • API isn't cleanly separated from the main site, harder to maintain
   • People may assume that adding .xml will work in places it doesn't

2. Use namespaced routing to create separate API controllers that only handle API functions, but still have access to the same models that the website uses

   Pros:

   • API is mostly separated
   • Still uses resource-full controllers

   Cons:

   • URLs have the form of site.com/api/resource.xml which may make people assume all resources are available
   • API is still part of the website code/project; thus, harder to maintain

3. Use route forwarding and constraints to forward all API calls to a Rack application

   Pros:

   • API is fully separated
   • Not required to use Resource-full style if we don't want to
   • URLs clearly show it's an API and you should check the docs to see what's available (at least, my mind works this way; I assume other dev's minds do too)

   Cons:

   • Harder to use models from website code
   • Easier to maintain as a separate project, but that means harder to integrate with existing site
   • Must keep codebases in sync since models may change for site features/bug fixes

Answer 1

I would propose that the API being in the same project as your website isn't a bad thing as long as the code is DRY*. Like you pointed out, having separate codebases is a challenge because you have to keep them in sync with every feature/bugfix you do. It's easier to maintain if they are in the same place. As long as you keep your code DRY, this method is the clear winner.

I would offer XML and JSON from the controllers with a subdomain handled by Rails's routing engine. When someone has picked up on the pattern of api.site.com/resource.xml and tries to access a resource that isn't there, it's really not a big deal. As long as your API is documented clearly and you fail/error gracefully when they try to access a resource not in your API, it should be just fine. I would try to return a message saying that resource isn't available and a url to your api documentation. This shouldn't be a runtime problem for any API consumers, as this should be part of discovering your API.

Just my $0.02.

*DRY = Don't Repeat Yourself. DRY code means you don't copy-paste or rewrite the same thing for your site and your api; you extract and call from multiple places.