I code it

Code and Life

使用Grape快速开发API

Grape简介

Grape是一个基于Rack的非常轻量级的框架,用于快速的开发API。一般来说,Rails对于单独的API来说,太过于重量级;而Sinatra虽然足够小巧,但是又没有为开发API提供足够的默认支持(如果从可控制性,灵活性上来说,Sinatra可能更好一些,但是如果有专门的更好用的工具,为什么不用呢?)。

安装非常简便:

1
$ gem install grape

或者使用在自己的Gemfile中,与其他的gem一起搭建API:

1
gem 'grape'

为既有系统添加API

简单一试

之前的一篇介绍ActiveRecord在既有系统中使用的文章中,我使用ActiveRecord为既有的数据库visitor中的三个表(visitor, listGroup, listGroupItem)建立了ruby对应的模型。现在我们可以为这些模型包装一组API,以方便客户端(消费者)可以通过web来访问。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
module MySys
    class API < Grape::API
        format :json

        resource :visitors do

            desc "get all visitor information"
            get do
                Visitor.limit(20)
            end

        end
    end
end

首先,MySys::API扩展了Grape::API。format定义我们的API会产生JSON格式的输出,resource定义了这一组API是为资源visitors提供的,因此访问API的url为:

1
http://localhost:9292/visitors/

当然,grape提供一个很方便的设置prefix,可以使得API的路径更有意义:

1
2
format :json
prefix "mysys"

url则相应地变为:

1
http://localhost:9292/mysys/visitors/

处理参数

在对参数的处理上,grape也非常灵活,比如接上例,我们想要获取某一个具体的用户的信息:

1
http://localhost:9292/visitors/8a9d82b13b9786e1013b978766150001

我们可以添加一个新的endpoint:

1
2
3
4
5
6
7
8
9
desc "return a visitor"
params do
    requires :visitor_uid, :type => String, :desc => "visitor id"
end
route_param :visitor_uid do
    get do
        Visitor.find(params[:visitor_uid])
    end
end

params中要求,需要一个类型为String的参数visitor_uid。然后在handler中,通过params来引用这个参数的值。

助手函数(Helper)

Grape允许开发者将编解码,权限校验等等的通用的操作分离出来,放入助手函数,这些Helper可以被所有的API使用:

1
2
3
4
5
6
7
8
9
10
11
helpers do
    def generate_default_visitor(email, site) 
        {
            :visitor_uid => SecureRandom.hex,
            :password_expiration => (Time.now + 60 * 60 * 24),
            :last_used_timestamp => (Time.now - 60 * 60 * 24),
            :visitor_login_id => email,
            :site_name => site
        }
    end
end

使用上边定义的助手函数generate_default_visitor

1
2
3
4
5
6
7
8
9
10
11
desc "create a visitor"
params do
    requires :email, :type => String, :desc => "Email address"
    requires :site, :type => String, :desc => "Site"
end
post do
    attr = generate_default_visitor(params[:email], params[:site])
    visitor = Visitor.new attr
    visitor.visitor_uid = attr[:visitor_uid]
    visitor.save
end

对API进行测试

通过Web测试API有非常多的方式,比如通过浏览器的插件(POSTMan),RSpec,但是我最喜欢,也是最轻便的方式是通过命令行工具curl:

1
curl http://localhost:9292/visitors/8a9d82b13b9786e1013b978766150001

或者:

1
curl -H "Content-Type: application/json" -X POST -d "{\"email\":\"jtqiu@tw.com\", \"site\":\"mysys\"}" http://localhost:9292/visitors/

命令行的程序curl是一个非常灵活,强大的工具,可以定制HTTP头信息,User Agent,支持所有的HTTP动词,最重要的是,在命令行很容易将工具们组合在一起,并完成自动化。

Comments