What are the best practices for designing a RESTful public API on Rails?

Question

Rails comes with RESTful resources out of the box, but do you use those for your actual public API? If so, how would you accomplish versioning of your API i.e. example.com/api/v2/foo/bar?

Answer 1

Typically, APIs for my applications are indeed built on the same resources that make up the HTML interface. For some (not me), that might be just using the code that comes out of the scaffold generator—but regardless of whether I write it custom or let the generator handle it, there are very few instances where I expose resources only to the programmatic API and not to the end user view.

Versioning hasn't been a problem for the applications I've built so far, but I can think of two ways to implement it.

1) You could add routes with the prefix 'v1,' 'v2,' etc., that set a parameter that you can then access in the controller to specify the processing to occur:

in routes.rb:

map.resources :posts, :path_prefix => '/:version'

in posts_controller.rb

class PostsController < ApplicationController
  def index
    respond_to do |format|
      format.xml do
        if params[:version] == 'v1'
          # ...
        else
          # ...
        end
      end
    end
  end
end

2) You might also consider adding a custom response format for each version

in initializers/mime_types.rb

Mime::Type.register_alias "application/xml", :v1
Mime::Type.register_alias "application/xml", :v2

in posts_controller.rb

class PostsController < ApplicationController
  def index
    respond_to do |format|
      format.v1 do
        # ...
      end
      format.v2 do
        # ...
      end
    end
  end
end

The former would give you URLs like example.com/v1/posts.xml and example.com/v2/posts.xml; the latter would give you URLs like example.com/posts.v1 and example.com/posts.v2