a well documented ruby api based on GrapeAPI.

grape_api_sample.rb

require 'grape'

module My
  class API < Grape::API
    prefix 'api'
    
    ## params key list
    #################################################################################################################
    # 1. login
    # 2. sign
    # 3. title
    ##################################################################################################################
    helpers do
      def current_user
        # auth/validation parts
        @current_user ||= User.validation_on_client_user(params)
        # add the below line if you use warden as your rack authentication filter
        env["warden"].custom_failure! if @current_user.nil?
        @current_user
      end
      
      def authenticate!
        error!("You have no rights to access the API.", 401) if current_user.blank?
      end
    end
    
    ## question API
    ################################################################################################################
    # method: POST
    # url: /api/questions/update
    # params: login, title, sign.
    # response: success => question.to_json
    #           failure => message with status => 403
    #################################################################################################################
    resources :questions do
      post "update" do
        authenticate!
        question = Question.create(:title => params[:title], :user => current_user)
        if question.save!
            question
        else
          error! "Unable to create your question.", 403
        end
      end
    end
    
    ## profile API
    ################################################################################################################
    # method: GET
    # url: /api/users/profile
    # params: login, sign.
    # response: {"karma":36,"badges":0}
    #################################################################################################################
    resources :users do
      get "profile" do
        authenticate!
        attr_hash = {
                     :badges => current_user.badgings_count,
                     :karma => current_user.karma_score, 
                     }
        attr_hash
      end
    end
  end
end