I'm currently writing the documentation for the API of my website.

I'm not sure about the "best" way to write the routes. I think twitter does a good job and I'd like to copy their url structure:

https://dev.twitter.com/docs/api
https://dev.twitter.com/docs/api/1/get/statuses/show/:id
https://dev.twitter.com/docs/api/1/post/statuses/retweet/:id

It would be something like:

 namespace :docs do
     resources :api do
         # and then... not sure
     end
 end

Not sure on how to write the routes for this part: /get/statuses/show/:id.

Should I just create a custom route?

match "/:verb/:resource/:action/:params" => "api#resource"

Or is there a better way?

What I ended up with, might help someone :)

Ibarcraft::Application.routes.draw do
    def api_versions; [:v1] end
    def api_verbs; [ :index, :show ] end

    constraints subdomain: "api" do
        scope module: "api", as: "api" do
            versions = api_versions

            versions.each do |version|
                namespace version, defaults: { format: "json" } do

                    # all my routes
                    resources :barcrafts, only: api_verbs do
                        collection do
                            get :search
                        end
                        scope module: "barcraft" do
                            resources :users, only: [:index]
                        end
                    end
                    # and more...

                end
            end

            match 'v:api/*path', to: redirect { |params, request| "/#{versions.last}/#{params[:path]}" + (params[:format] ? ".#{params[:format]}" : "") }
            match '*path', to: redirect { |params, request| "/#{versions.last}/#{params[:path]}" + (params[:format] ? ".#{params[:format]}" : "") }
        end
    end
end

• ruby-on-rails
• ruby-on-rails-3
• rest
• documentation
• routes

Yes you need custom route.

But note, that :action key is reserved for controller's action name, better use something like :action_name