grape入门

1.Grape是运行在rack或与rails/sinatra配合使用的一种restful风格的ruby微框架,通过提供简单的DSL(领域特定语言)简化APIs开发.它内置支持mutiple formats(),subdomain/prefix restriction, versioning等通用约束(ruby约束高于配置).详见http://intridea.github.io/grape/.

2.安装Grape

gem install grape

或者编辑Gemfile.

gem "grape"

然后

bundle install

 

3.基础用法

Grape APIs和Rack应用继承自Grape::API.

下面展示一段用Grape写的简单的twitter 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

关于上面代码的简单解释:

将API文件放在/app/api文件下，并且修改/config/application.rb文件：

config.paths.add "app/api", glob: "**/*.rb"

config.autoload_paths += Dir["#{Rails.root}/app/api/*"]

并且修改路由文件/config/routes.rb:

mount   Twitter::API  => '/'

 

3.调用API

使用mount方法:

class Twitter::API < Grape::API

  mount Twitter::APIv1

  mount Twitter::APIv2

end

class Twitter::API < Grape::API

  mount Twitter::APIv1 => '/v1'

end

4.为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

           }

          ]

end

get :public_timeline do

  Status.limit(20)

end

details:更加详细的描述

params:直接从实体定义参数

success:实体对象的默认使用路由

failure:请求失败返回的http代码

(====续=====)

参数认证和约束

（1）.在block中定义设置参数的约束项：

params do

  requires :id, type: Integer  

  optional :text, type: String, regexp: /^[a-z]+$/  #text全是小写字母

  group :media do #参数嵌套；与[:id]协同

    requires :url

  end

end

put ':id' do

  # params[:id] is an Integer

end

（2）.命名空间认证和约束

允许定义参数以及在命名空间内部使用各种方法，命名空间就是一个sandbox，叫做module;采用这种模块化机制可以有效限定作用域；

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]) #通过 ：user_id获取：status_id;

    end

  end

end

（3）用户认证

class AlphaNumeric < Grape::Validations::Validator

  def validate_param!(attr_name, params)

    unless params[attr_name] =~ /^[[:alnum:]]+$/  #[:alnum]  posix字符类字母数字类

      throw :error, status: 400, message: "#{attr_name}: must consist of alpha-numeric characters"

    end

  end

end

params do

  requires :text, alpha_numeric: true  #也可这样约束类型

end

class Length < Grape::Validations::SingleOptionValidator

  def validate_param!(attr_name, params)

    unless params[attr_name].length <= @option

      throw :error, status: 400, message: "#{attr_name}: must be at the most #{@option} characters long"

    end

  end

end

params do

  requires :text, length: 140

end

请求头

get do

  error!('Unauthorized', 401) unless headers['Secret-Password'] == 'swordfish'

end



get do

  error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'

end

header "X-Robots-Tag", "noindex"

路由

 

get ':id', requirements: { id: /[0-9]*/ } do  #Regexp 条件过滤

  Status.find(params[:id])

end



namespace :outer, requirements: { id: /[0-9]*/ } do

  get :id do

  end



  get ":id/edit" do

  end

end

module StatusHelpers

  def user_info(user)

    "#{user} has statused #{user.statuses} status(s)"

  end

end



class API < Grape::API

  # define helpers with a block

  helpers do

    def current_user

      User.find(params[:user_id])

    end

  end



  # or mix in a module

  helpers StatusHelpers



  get 'info' do

    # helpers available in your endpoint and filters

    user_info(current_user)

  end

end