Grape是一个基于Ruby的REST风格的微型框架。它设计运行于Rack之上或是与现有框架集成，例如Rails和Sinatra，它可以方便的开发REST风格的API。它有共同约定的支持，支持多种模式，子域名/前缀绑定，内容约定，版本以及更多。
当前版本为0.13.0。升级前请阅读升级文档。
需要帮助？Grape谷歌讨论组
Grape有一个可用的gem，安装它：
gem install grape
如果你是用Bundler, 添加它到Gemfile中
gem 'grape'
执行 bundle install。
Grape API通过Rack创建Grape::APIde的子类来创建应用程序。下面的这个简单例子展示了搭建推特部分API环境。
module Twitter
class API < Grape::API
version 'v1', using: :header, vendor: 'twitter'
format :json
prefix :api
helpers do
def current_user
@current_user ||= User.authorize!(env)
end
def authenticate!
error!('401 Unauthorized', 401) unless current_user
end
end
resource :statuses do
desc "Return a public timeline."
get :public_timeline do
Status.limit(20)
end
desc "Return a personal timeline."
get :home_timeline do
authenticate!
current_user.statuses.limit(20)
end
desc "Return a status."
params do
requires :id, type: Integer, desc: "Status id."
end
route_param :id do
get do
Status.find(params[:id])
end
end
desc "Create a status."
params do
requires :status, type: String, desc: "Your status."
end
post do
authenticate!
Status.create!({
user: current_user,
text: params[:status]
})
end
desc "Update a status."
params do
requires :id, type: String, desc: "Status ID."
requires :status, type: String, desc: "Your status."
end
put ':id' do
authenticate!
current_user.statuses.find(params[:id]).update({
user: current_user,
text: params[:status]
})
end
desc "Delete a status."
params do
requires :id, type: String, desc: "Status ID."
end
delete ':id' do
authenticate!
current_user.statuses.find(params[:id]).destroy
end
end
end
end上面的例子创建的程序可与config.ru rackup来运行Rack应用，
run Twitter::API
并响应以下路由
GET /api/statuses/public_timeline
GET /api/statuses/home_timeline GET /api/statuses/:id POST /api/statuses PUT /api/statuses/:id DELETE /api/statuses/:id
Grape也能自动响应HEAD和option的所有GET及其他路由请求。
如果你想要在Grape内使用ActiveRecord，你需要确保ActiveRecord连接正常。一个简单的方法是，在config.ru文件中在mounting Grape之前使用ActiveRecord的ConnectionManagement。
use ActiveRecord::ConnectionAdapters::ConnectionManagement run Twitter::API
如果你想安装到如除了Sinatra或其他框架中，你可以很容易的使用Rack::Cascade：
# Example config.rurequire 'sinatra'require 'grape'class API < Grape::API
get :hello do
{ hello: "world" }
endendclass Web < Sinatra::Base
get '/' do
"Hello world."
end
end
use Rack::Session::Cookierun Rack::Cascade.new [API, Web] 请将API文件放到app/api下。Rails以命名约定来加载匹配类文件。在我们的例子中，Twitter::API应该位于app/api/twitter/api.rb。
修改application.rb：
config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb') config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
修改config/routes文件。
mount Twitter::API => '/'
另外，如果你是用的Rails4.0以上版本和你使用ActiveRecord作为默认模型层，你可能希望使用HASHIE-forbidden_attributes。它禁用了模型层的健壮参数，可以让你使用Grape的自身验证代替它。
# Gemfile
gem "hashie-forbidden_attributes"
查看以下的代码，在开发中改变代码启用自动加载。
你可以在API装配多套接口实现。它不必是不同的版本，但也可以是相同的API的组件。
class Twitter::API < Grape::API mount Twitter::APIv1 mount Twitter::APIv2 end
你也可以装配到一个路径，这类似于使用前缀方式的API。
class Twitter::API < Grape::API mount Twitter::APIv1 => '/v1' end
有四种方式，可以访问API。:path, :header, :accept_version_header和:param。默认是:path。
version 'v1', using: :path
通过这种策略，客户端需要在url传递需要的版本。
curl http://localhost:9292/v1/statuses/public_timeline
version 'v1', using: :header, vendor: 'twitter'
通过这种策略，需要传递需要的HTTP报头头信息。
curl -H Accept:application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
缺省情况下，如果没有提供报头信息，则它默认匹配Path模式。为了规避这种行为，可以使用:strict选项。当此选项位true，没有提供报头，将返回406错误。
缺省情况下，GET请求返回200，POST返回201。你可以使用status查询和设置HTTP状态码。
post do
status 202 if status == 200 # do some thing endend
你也可以使用status Rack提供的状态码符号来设置或查询。
post do
status :no_contentend
version 'v1', using: :accept_version_header
通过这种策略客户端需要传递版本在Accept-Version信息。
curl -H "Accept-Version:v1" http://localhost:9292/statuses/public_timeline
默认情况下，如果没有提供报头，将匹配Path模型。这种行为类似于Rails路由。为了规避这种违约行为，可以使用:strict选项。当这个选项为true，当报头不正确，将返回406错误。
version 'v1', using: :param
使用这种版本策略，客户端需要将版本作为请求参数，可以是url查询参数或是请求体。
curl http://localhost:9292/statuses/public_timeline?apiver=v1
查询参数默认名称为apiver，但你可以指定使用的:parameter选项。
version 'v1', using: :param, parameter: "v"
curl http://localhost:9292/statuses/public_timeline?v=v1
你可以为api添加描述和命名空间。
desc "Returns your public timeline." do
detail 'more details'
params API::Entities::Status.documentation
success API::Entities::Entity
failure [[401, 'Unauthorized', "Entities::Error"]]
named 'My named route'
headers [XAuthToken: {
description: 'Valdates your identity',
required: true
},
XOptionalHeader: {
description: 'Not really needed',
required: false
}
]endget :public_timeline do
Status.limit(20)
enddetail: 一个更为详细的描述
params: 直接从实体定义参数
success：(原单位)实体默认使用这条路由
failure：(原http返回码)当失败时，返回http返回码和实体
named：给路由定义一个名字，可以在文档hash里找到它
haders：定义使用的报头
请求参数可以通过params这个hash对象来获取，包括GET, POST, Put参数，以及其他你指定的路由参数字符串。
get :public_timeline do Status.order(params[:sort_by])end
参数会自动填充从POST请求主体和PUT表单输入、JSON和XML的内容类型。
curl -d '{"text": "140 characters"}' 'http://localhost:9292/statuses' -H Content-Type:application/json -vpost '/statuses' do Status.create!(text: params[:text])end
支持部分POST和PUT请求提交。
下面这个请求：
curl --form image_file='@image.jpg;type=image/jpg' http://localhost:9292/upload
这个Grape节点：
post "upload" do # file in params[:image_file]end
在冲突的情况下，无论是：
路由字符串参数
GET，POST和PUT参数
POST和PUT请求体
按顺序来匹配。
Grape让你只能访问被你声明的参数块，它过滤掉已传递参数。比如我们有如下API：
format :jsonpost 'users/signup' do { "declared_params" => declared(params) }end如果我们不指定任何参数，这个声明将返回空的Hashie::Mash实例。
请求
curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "last_name": "last name"}}'返回
{ "declared_params": {}}一旦我们添加了需要的参数，将返回声明的参数
format :jsonparams do
requires :user, type: Hash do
requires :first_name, type: String
requires :last_name, type: String
end
end
post 'users/signup' do
{ "declared_params" => declared(params) }
endcurl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "last_name": "last name", "random": "never shown"}}'返回
{
"declared_params": {
"user": {
"first_name": "first name",
"last_name": "last name"
}
}
}返回的是Hashie::Mash的实例，你能通过点号+参数的形式访问它。
declared(params).user == declared(params)["user"]
包括丢失参数
默认情况下，delared(params)返回具有nil值的参数，如果只想返回不为nil值的参数，你可以使用include_missing选项。默认情况下它为true，请看下面的API：
format :jsonparams do
requires :first_name, type: String
optional :last_name, type: Stringend
post 'users/signup' do
{ "declared_params" => declared(params, include_missing: false) }
end请求
curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "random": "never shown"}}'当include_missing:false返回：
{
"declared_params": {
"user": {
"first_name": "first name"
}
}
}当include_missing:true返回
{
"declared_params": {
"first_name": "first name",
"last_name": null
}
}
这也适用于嵌套hash：
format :jsonparams do
requires :user, :type => Hash do
requires :first_name, type: String
optional :last_name, type: String
requires :address, :type => Hash do
requires :city, type: String
optional :region, type: String
end
end
end
post 'users/signup' do
{ "declared_params" => declared(params, include_missing: false) }
end请求
curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "random": "never shown", "address": { "city": "SF"}}}'当include_missing:false时返回：
{
"declared_params": {
"user": {
"first_name": "first name",
"address": {
"city": "SF"
}
}
}
}当include_missing:true时返回：
{
"declared_params": {
"user": {
"first_name": "first name",
"last_name": null,
"address": {
"city": "Zurich",
"region": null
}
}
}
}注意，传递nil值并不被认为是丢失参数，例如下面将include_missing设置为false：
请求
curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "last_name": null, "address": { "city": "SF"}}}'当include_miss设置为false返回
{
"declared_params": {
"user": {
"first_name": "first name",
"last_name": null,
"address": { "city": "SF"}
}
}
}你可以通过params块定义验证和强制选项。
params do requires :id, type: Integer optional :text, type: String, regexp: /^[a-z]+$/ group :media do requires :url end optional :audio do requires :format, type: Symbol, values: [:mp3, :wav, :aac, :ogg], default: :mp3 end mutually_exclusive :media, :audioendput ':id' do # params[:id] is an Integerend
当一个类型指定为隐式验证，随后输出类型确保如声明的一样。
可选参数可以有默认值
params do optional :color, type: String, default: 'blue' optional :random_number, type: Integer, default: -> { Random.rand(1..100) } optional :non_random_number, type: Integer, default: Random.rand(1..100)end 默认值将会被传递到验证选项，下面的例子，如果没有提供明确的值，将会验证失败。
params do optional :color, type: String, default: 'blue', values: ['red', 'green']end
下面的正确实施，将通过验证。
params do optional :color, type: String, default: 'blue', values: ['blue', 'red', 'green']end
以下的都是有效参数类型。
Integer
Float
BigDecimal
Numeric
Date
DateTime
Time
Boolean
String
Symbol
Rack::Multipart::UploadedFile
除了上面支持的类型，任何类都可以使用，只要它定义一个类方法parse，此方法接收一个字符串参数和返回类实例，或抛出异常，表明该值无效。
例如：
class Color
attr_reader :value def initialize(color) @value = color end def self.parse(value) fail 'Invalid color' unless %w(blue red green).include?(value) new(value) endend# ...params do requires :color, type: Color, default: Color.new('blue')endget '/stuff' do # params[:color] is already a Color. params[:color].valueend 嵌套参数同样可以用requires, optional修饰。在上面的例子中，这意味着params[:media][:url][:id]连同params是必须的，而params[:audio][:format]才需要params[:audio]的存在。block, group, requires, optional可以接受一个额外的选项类型，他可以是数组和Hash，默认是Hash。根据值的类型，参数会被视为hash中的值或hash数组中的值。
params do optional :preferences, type: Array do requires :key requires :value end requires :name, type: Hash do requires :first_name requires :last_name endend
假设你的一些参数和其他参数有关。你可以通过在你的参数块通过given方法标识这种依赖，像这样：
params do optional :shelf_id, type: Integer given :shelf_id do requires :bin_id, type: Integer endend
allow_blank:
可以通过使用allow_blank选项，确保参数包含一个值。默认情况下，requires修饰的参数只验证必须传递一个值，而不管值是什么。如果allow_blank为false，则这个值不能是false、空值和空白字符串。
allow_blank可以根据需要修饰requires和optional，如果和requires结合，它必须传递值，且不为空值。如果与optional结合，它可以不传递值，一旦传递，不能为空。
params do requires :username, allow_blank: false optional :first_name, allow_blank: falseend
values
values选项可以限定为一组特定值。
默认值自动评估。上面的例子:non_random_num将会每次调用方法来产生值。默认值可以使用lambda表达式，如random_number。
params do requires :status, type: Symbol, values: [:not_started, :processing, :done] optional :numbers, type: Array[Integer], default: 1, values: [1, 2, 3, 5, 8]end
通过:values提供一组值参数，可以使用Range#include?验证值是否在范围内。
params do requires :latitude, type: Float, values: -90.0..+90.0 requires :longitude, type: Float, values: -180.0..+180.0 optional :letters, type: Array[String], values: 'a'..'z'end
注意使用范围类型时，这两个范围类型与你指定的:type选项一致(如果没有提供:type选项，则它等同于范围端点第一个端点)。所以下面的代码是无效的
params do requires :invalid1, type: Float, values: 0..10 # 0.kind_of?(Float) => false optional :invalid2, values: 0..10.0 # 10.0.kind_of?(0.class) => falseend
:values选项也可以支持一个Proc，每次延迟执行。例如，你可能希望值是HashTag模型的值。
params do requires :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }endregexp
:regexp选项限制参数必须匹配正则表达式。如果不匹配，将返回错误。注意它必须存在requires和optional选项。
params do requires :email, regexp: /.+@.+/end
下面的例子传递的参数无价值，验证器将通过。可以使用:allow_blank 为false避免。
params do requires :email, allow_blank: false, regexp: /.+@.+/end
mutually_exclusive
mutually_exclusive确保参数不同时存在
params do optional :beer optional :wine mutually_exclusive :beer, :wineend
设置多组值
params do optional :beer optional :wine mutually_exclusive :beer, :wine optional :scotch optional :aquavit mutually_exclusive :scotch, :aquavitend
危险：不要对requires修饰的参数定义互斥，这意味着两者都有效，从而失去互斥的意义。一个requires参数与optional参数互斥意味着后者永远有效。
exactly_one_of
通过exactly_one_of，确保正好一个参数被选择。
params do optional :beer optional :wine exactly_one_of :beer, :wineend
at_least_one_of
这个选项，确保至少有一个参数被选中。
params do optional :beer optional :wine optional :juice at_least_one_of :beer, :wine, :juiceend
all_or_none_of
这个选项，要么全部参数提供，要么都不提供
params do optional :beer optional :wine optional :juice all_or_none_of :beer, :wine, :juiceend
mutually_exclusive, exactly_one_of, at_least_one_of, all_or_none_of所有这些方法都可以在任何嵌套中使用。
params do requires :food do optional :meat optional :fish optional :rice at_least_one_of :meat, :fish, :rice end group :drink do optional :beer optional :wine optional :juice exactly_one_of :beer, :wine, :juice end optional :dessert do optional :cake optional :icecream mutually_exclusive :cake, :icecream end optional :recipe do optional :oil optional :meat all_or_none_of :oil, :meat endend
命名空间允许参数定义以及对每个方法应用命名空间。
namespace :statuses do params do requires :user_id, type: Integer, desc: "A user ID." end namespace ":user_id" do desc "Retrieve a user's status." params do requires :status_id, type: Integer, desc: "A status ID." end get ":status_id" do User.find(params[:user_id]).statuses.find(params[:status_id]) end endend
命名空间有许多别名，包括：group, resource, resources和segment。你可以在你的API使用最适合你读的方式。
你可以方便的使用route_param 路由参数 定义为一个命名空间。
class AlphaNumeric < Grape::Validations::Base def validate_param!(attr_name, params) unless params[attr_name] =~ /^[[:alnum:]]+$/ fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must consist of alpha-numeric characters" end endend
params do requires :text, alpha_numeric: trueend
你当然也可以创建一个带参数的自定义的类
class Length < Grape::Validations::Base def validate_param!(attr_name, params) unless params[attr_name].length <= @option fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must be at the most #{@option} characters long" end endendparams do requires :text, length: 140end
强制验证和错误引发的异常放在Grape::Exceptions:ValidationErrors类型集合中。如果异常未被补货，它将响应400错误和错误message。验证错误由参数名分组，可以通过Grape::Exceptions:ValidationErrors#errors访问。
默认的响应对象是一个Grape::Exceptions:ValidationErrors对象，它是一个对人友好的信息字符串。例如："beer, wine are mutually exclusive",例如下面的例子。
params do optional :beer optional :wine optional :juice exactly_one_of :beer, :wine, :juiceend
你可以捕获处理Grape::Exceptions:ValidationErrors异常和输出自定义的错误信息或通过JSON API将单独参数对应的错误信息输出。下面rescue_form例子生成[{"params":["beer","wine"],"messages":["are mutually exclusive"]}]。
format :jsonsubject.rescue_from Grape::Exceptions::ValidationErrors do |e| error! e, 400end
Grape::Exceptions::ValidationErrors#full_messages返回验证错误信息数组。
Grape::Exceptions::ValidationErrors#message返回错误信息数组串联成的一个字符串。
要响应验证消息为数组，可以使用Grape::Exceptions::ValidationErrors#full_message。format :json subject.rescue_from Grape::Exceptions::ValidationErrors do |e| error!({ messages: e.full_messages }, 400) end
Grape支持I18n，但如果没有提供对应的语言文件，它会默认使用英语。查看en.yml文件中的消息键。
请求头可以使用 headers 的帮助 或 evn中的原始信息。
get do error!('Unauthorized', 401) unless headers['Secret-Password'] == 'swordfish'endget do error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'end 你可以通过header 中的API设置一个响应头
header 'X-Robots-Tag', 'noindex'
当通过error!引发异常，可以传递响应头参数
error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
或者，您可以使用 requirements 定义正则表达式在命名空间或终端节点上(方法)。如果requirements正则表达式匹配，这个路由也就匹配了。
get ':id', requirements: { id: /[0-9]*/ } do Status.find(params[:id])endnamespace :outer, requirements: { id: /[0-9]*/ } do get :id do end get ":id/edit" do endend一般，我们可以使用二进制格式发送原生数据。
class API < Grape::API get '/file' do content_type 'application/octet-stream' File.binread 'file.bin' end end
你可以通过body显式的设置响应的内容。
class API < Grape::API get '/' do content_type 'text/plain' body 'Hello World' # return value ignored end end
使用body false会返回204没有内容或是没有没有内容类型。
你还可以设置响应文件类对象。注意：Rack返回响应之前将阅读你的整个枚举。如果你想响应流类型，请看streem.
class FileStreamer
def initialize(file_path)
@file_path = file_path
end
def each(&blk)
File.open(@file_path, 'rb') do |file|
file.each(10, &blk)
end
end
end
class API < Grape::API
get '/' do
file FileStreamer.new('file.bin')
end
end如果你想将文件类响应为流，可以使用Rack::Chunchked来使用流。
class API < Grape::API
get '/' do
stream FileStreamer.new('file.bin')
end
endGrape内置基本和摘要式身份认证(在给定的块中执行代码).认证适用于当前的命名空间和任何子节点，而不包括父命名空间。
基本认证
http_basic do |username, password|
# verify user's password here
{ 'test' => 'password1' }[username] == password
end摘要认证
http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
# lookup the user's password here
{ 'user1' => 'password1' }[username]
end注册自定义中间件进行身份认证
Grape可以使用自定义的中间件进行身份认证。如果实现可以看看Rack::Auth::Basic或类似的实现。
注册一个中间件需要以下选项：
label - 您的身份验证使用的名字
MiddlewareClass - MiddlewareClass用于身份验证
optionlookupproc - 提供一个Proc作为参数给这个选项(返回值为数组，中间件参数)
例如：
Grape::Middleware::Auth::Strategies.add(:my_auth, AuthMiddleware, ->(options) { [options[:realm]] } )
auth :my_auth, { realm: 'Test Api'} do |credentials|
# lookup the user's password here
{ 'user1' => 'password1' }[username]
end使用warden-oauth2或rack-oauth2来支持OAuth2。
Grape的路由可以在运行时反射。这主要对生成的文档非常有用。
Grpae暴露API版本和编译的路由数组。每个路由都包括一个routeprefix、routeversion、routenamespace, routemethod, routepath和routeparams。你可以通过route_setting添加自定义路由设置路由。
class TwitterAPI < Grape::API version 'v1' desc "Includes custom settings." route_setting :custom, key: 'value' get do end end
在运行时检查路由。
TwitterAPI::versions # yields [ 'v1', 'v2' ]
TwitterAPI::routes # yields an array of Grape::Route objects
TwitterAPI::routes[0].route_version # => 'v1'
TwitterAPI::routes[0].route_description # => 'Includes custom settings.'
TwitterAPI::routes[0].route_settings[:custom] # => { key: