在 Rails 上设计 RESTful 公共 API 的最佳实践是什么？

Question

Rails 提供开箱即用的 RESTful 资源，但您是否将这些资源用于实际的公共 API？如果是这样，您将如何完成 API 的版本控制，即example.com/api/v2/foo/bar？

Answer 1

通常，我的应用程序的 API 确实建立在构成 HTML 界面的相同资源之上。对于某些人（不是我），这可能只是使用来自脚手架生成器的代码——但无论我是自定义编写它还是让生成器处理它，很少有我只将资源公开给程序API 而不是最终用户视图。

版本控制对于我迄今为止构建的应用程序来说不是问题，但我可以想到两种方法来实现它。

1) 您可以添加前缀为“v1”、“v2”等的路由，设置一个参数，然后您可以在控制器中访问该参数以指定要进行的处理：

在 routes.rb 中：

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

在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) 您也可以考虑为每个版本添加自定义响应格式

在初始化程序/mime_types.rb 中

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

在posts_controller.rb中

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

前者会给你像 example.com/v1/posts.xml 和 example.com/v2/posts.xml 这样的 URL；后者会给你像 example.com/posts.v1 和 example.com/posts.v2 这样的 URL