grape: A Ruby framework for rapid API development with great conventions.

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

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

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代码

(====未完=====)