Learn Ruby on Rails API - GrapeAPI
Bài đăng này đã không được cập nhật trong 9 năm
I. API Basics and Building Your Own
1. Giới thiệu
Làm việc với APIs rất tuyệt vời nhưng cũng không kém phần khó chịu. API một mặt giao tiếp với các ứng dụng, cải thiện cách tiếp cận và đưa ra những “cool factor” cho ứng dụng của bạn, mặt khác liên quan nhiều tới viêch đọc tài liệu để tìm ra chiến lược xác thực và phân tích các thông báo lỗi(không tốt hoặc không tồn tại) bằng cách đọc lời giải thích của Skillcrush và sau đó đọc bit đầu tiên của article này để catch up.
API là 1 khái niệm rộng, ứng dụng của bạn và một ứng dụng khác hoặc các thành phần trong cùng một ứng dụng giao tiếp được với nhau là nhờ thông qua một số loại API; các thành phần trong cùng một ứng dụng ít nhiều độc lập với nhau, đóng vai trò như một ứng dụng con cùng với data cần thiết hoàn thành nhiệm vụ cụ thể của mình. Mỗi thứ như vậy trong đó là một API. Khi bạn xây dựng các ứng dụng có chức năng front-end năng động hơn (ví dụ như trang ứng dụng chuyên Javascript phức tạp hoặc đơn giản chỉ là các cuộc gọi AJAX), đơn giản chỉ cần 1-2 dòng code trong controller để trả về kiểu JSON hoặc XML thay vì HTML.
Dưới đây là cách để xây dựng 1 ứng dụng API
2. API Basics
Ứng dụng Rails về cơ bản đã là một API. Trình duyệt web đang chạy của bạn cũng là một chương trình, nó có tác dụng tạo một API request tới ứng dụng Rails của bạn khi bạn yêu cầu một trang mới. Nó mặc định render ra 1 trọng tải HTML tương ứng.
Nếu bạn muốn tạo một request mà không muốn đi qua trình tự rắc rối trên (Ví dụ như : bạn cần lấy một danh sách đối tượng nào đó mà không quan tâm tới cấu trúc HTML của trang(bỏ qua view) thay vào đó là đi thẳng tới dữ liệu) thì sự lựa chọn tốt nhất dành cho bạn là sử dụng JSON hoặc XML. Tức là sẽ submit một request tới URL tương ứng yêu cầu một JSON hoặc XML response.Nếu thiết lập controller đúng, bạn sẽ nhận lại được một mảng đối tượng JSON đơn giản chứa tất cả các đối tượng bạn yêu cầu.
Ngoài ra, với các APIs bên ngoài, ví dụ như bạn muốn lấy các tweet gần đây của người dùng từ Twitter, bạn chỉ cần chỉ cách cho ứng dụng Rails của bạn cách giao tiếp với API của Twitter (ví dụ như xác nhận người dùng), submit request và xử lý các bó tweet trả về.
3. Building APIs
3.1 The Basics
Nếu bạn muốn ứng dụng Rails của bạn trả về JSON thay vì HTML, bạn cần chỉ cho controller cách làm điều đó. Cùng 1 controller action có thể trả về những loại khác nhau phụ thuộc vào việc tạo request bình thường từ trình duyệt hay từ một API được gọi từ dòng lệnh. Nó quyết định loại của request đang được thực hiện dựa trên phần mở rộng của tập tin được yêu cầu, example.xml hay example.json
Bạn có thể nhìn thấy được loại của tập tin ở trên nhật ký hệ thống :
Started GET “/posts/new” for 127.0.0.1 at 2013-12-02 15:21:08 -0800 Processing by PostsController#new as HTML
Dòng đầu tiên nói cho bạn biết loại URL được yêu cầu, dòng thứ 2 cho biết nó sẽ đi đâu và thực hiện tiến trình như thế nào. Nếu sử dụng 1 .json extension thì log thì như sau :
Started GET “/posts.json” for 127.0.0.1 at 2013-12-04 12:02:01 -0800 Processing by PostsController#index as JSON
Nếu bạn thực hiện không đúng ở controller thì sẽ có lỗi thông báo ra cho bạn.
3.2 Rendering JSON or XML
Sử dụng method #respond_to để chỉ cho controller cách trả về tập tin file JSON hoặc XML:
class UsersController < ApplicationController
def index
@users = User.all
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @users }
format.json { render :json => @users }
end
end
end
#respond_to chuyển các khối vào 1 đối tượng định dạng mà bạn yêu cầu. Nếu bạn không làm gì, html sẽ render ra các view tương ứng mặc định của Rails (ví dụ như : app/views/index.html.erb)
Chức năng #render đủ thông minh để lấy ra được template tương ứng từ 1 tập các định dạng. Khi chạy qua từ khóa :json, chương trình sẽ gọi #to_json trên giá trị, trong trường hợp này là @users. Điều này làm cho các đối tượng Ruby trở thành chuỗi JSON có thể chuyển tới được ứng dụng yêu cầu.
3.2.1. Chỉ định thuộc tính trả về
Trong model : sử dụng #as_json
# app/models/user.rb
class User < ActiveRecord::Base
# Option 1: Purely overriding the #as_json method
def as_json(options={})
{ :name => self.name } # NOT including the email field
end
# Option 2: Working with the default #as_json method
def as_json(options={})
super(:only => [:name])
end
end
Trong controller, chỉ cần sử dụng render JSON như bình thường (nó sẽ luôn trả về JSON mặc dù có request HTML hay không)
# app/controllers/users_controller.rb
class UsersController < ApplicationController
def index
render json: User.all
end
end
3.2.2. Rendering Nothing or Errors
Giúp trả về một HTTP status code
# app/controllers/users_controller.rb
class UsersController < ApplicationController
def index
render nothing: true, status: 404
end
def update
respond_to do |format|
if save!
format.html {redirect_to redirect_path}
format.json do
render json: @user, status: :ok, content_type: “text/json”
end
else
format.html do
render :show
end
format.json do
render json: @user.errors, status: :ng, content_type: “text/json”
end
end
end
end
end
Status codes có thể dùng được theo 2 kiểu số và chữ (ví dụ như 404 hoặc :ok)
- Một số status codes thường dùng :
200 – :ok
204 – :no_content
400 – :bad_request
403 – :forbidden
401 – :unauthorized
404 – :not_found
410 – :gone
422 – :unprocessable_entity
500 – :internal_server_error
Chi tiết có thể xem tại đây : http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
Cách tạo trang báo lỗi động trong Rails :
http://wearestac.com/blog/dynamic-error-pages-in-rails
4. Authentication
Mỗi một API là một cổng vào ứng dụng của bạn. Nếu bạn không muốn ai cũng có thể truy cập, chỉnh sửa và xóa dữ liệu của bạn thì bạn cần chỉ định những người dùng nào sẽ được quyền làm những việc đó. Cách để bảo đảm an ninh cho API của bạn là Access Tokens. Chúng ta cần tạo 1 model cụ thể có tên là ApiKey để lưu trữ token, token sẽ chứa 32 ký tự hexa ví dụ như dưới đây:
class ApiKey < ActiveRecord::Base
attr_accessible :user, :token
belongs_to :user
before_create :generate_token
private
def generate_token
begin
self.token = SecureRandom.hex.to_s
end while self.class.exists?(token: token)
end
end
Class rất đơn giản, nó sẽ gọi method generate_token, cái mà sẽ tạo 1 chuỗi ký tự hexa duy nhất khi class được khởi tạo. Mỗi một người dùng khi đăng ký sẽ được cấp cho một api key.
app/models/user.rb
class User < ActiveRecord::Base
…
has_one :api_key, dependent: :destroy
after_create :create_api_key
…
private
def create_api_key
ApiKey.create user: self
end
end
Khi nhận 1 request, chỉ cần kiểm tra xem token có đúng hay không và tìm current user tương ứng. Việc xác nhận này được thực hiện trong Application controller
#app/controllers/appliation_controller.rb
include ActionController::HttpAuthentication::Token::ControllerMethods
include ActionController::MimeResponds
class ApplicationController < ActionController::API
private
def restrict_access
unless restrict_access_by_params || restrict_access_by_header
render json: {message: "Invalid API Token"}, status: 401
return
end
@current_user = @api_key.user if @api_key
end
def restrict_access_by_header
return true if @api_key
authenticate_with_http_token do |token|
@api_key = ApiKey.find_by_token(token)
end
end
def restrict_access_by_params
return true if @api_key
@api_key = ApiKey.find_by_token(params[:token])
end
end
Hỗ trợ access token cả header và params, để được hỗ trợ xác thực header cần include module ActionController::HttpAuthentication::Token::ControllerMethods (đã bị vô hiệu hóa ở Rails::API mặc định). Để chắc chắn token sẽ được kiểm tra mỗi khi gọi API, cần thêm before_filter vào controller:
before_filter :restrict_access
5. Testing
Khi test 1 API bạn nên test cả 2 phần là nội dung response và HTTP status codes. Ví dụ :
#spec/api/tasks_api_spec.rb
require "spec_helper"
require "api/api_helper"
require "fakeweb"
require "timecop"
describe "Tasks API" do
before :each do
FactoryGirl.create :integration
FactoryGirl.create :project
FactoryGirl.create :task
Project.last.integrations << Integration.last
end
# GET /tasks/:id
it "should return a single task" do
api_get "tasks/#{Task.last.id}", {token: Integration.last.user.api_key.token}
response.status.should == 200
project = JSON.parse(response.body)
project["id"].should == Task.last.id
project["project_id"].should == Task.last.project_id
project["source_name"].should == Task.last.source_name
project["source_identifier"].should == Task.last.source_identifier
project["current_state"].should == Task.last.current_state
project["story_type"].should == Task.last.story_type
project["current_task"].should == Task.last.current_task
project["name"].should == Task.last.name
end
…
end
Test riêng từng action trong controller:
#spec/api/api_helper.rb
def api_get action, params = {}, version = "1"
get "/api/v#{version}/#{action}", params
JSON.parse(response.body) rescue {}
end
def api_post action, params = {}, version = "1"
post "/api/v#{version}/#{action}", params
JSON.parse(response.body) rescue {}
end
def api_delete action, params = {}, version = "1"
delete "/api/v#{version}/#{action}", params
JSON.parse(response.body) rescue {}
end
def api_put action, params = {}, version = "1"
put "/api/v#{version}/#{action}", params
JSON.parse(response.body) rescue {}
end
6. Getting Started
Trang web này là một trang web hữu ích, giúp cho bạn làm quen với việc chạy lệnh API trên terminal
https://developer.github.com/guides/getting-started/
II. GrapeAPI
A. Tổng quan
1. Giới thiệu
Grape là một REST-like API micro-framework cho Ruby. Nó được thiết kế để chạy trên Rack hoặc bổ sung cho mô hình ứng dụng web hiện có như Rails và Sinatra bằng việc cung cấp một DSL đơn giản để dễ dàng phát triển các RESTful API. Nó được xây dựng để hỗ trợ cho các giao tiếp chung (common convention), chứa nhiều format, giảm thiểu subdomain/prefix, đàm phán nội dung…
2. Cài đặt
Cài đặt gem:
Cách 1 : Run $ gem install grape
Cách 2 : thêm gem "grape" vào Gemfile, chạy bundle install
3. Basic Usage
Grape APIs là các ứng dụng Rack được tạo bởi subclassing Grape::API. Dưới đây là một ví dụ đơn giản cho thấy một số tính năng phổ biến của Grape trong việc tái tạo các phần của 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
4. Grape on Rails
Hãy thay thế các file APIs thành app/api. Rails mong muốn một thư mục con tương ứng với tên của các module Ruby và một tên file tương ứng với tên của các class. Ví dụ tên file local và thư mục cho Twitter::API nên là app/api/twitter/api.rb
Chính sửa #application.rb:
config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
Chính sửa #config/routes:
mount Twitter::API=> '/'
Chi tiết : https://github.com/intridea/grape#rails
B. Building RESTful API using Grape in Rails
1. Getting Started
Tạo 1 app:
$ rails new emp_api –skip-bundle
Thêm dòng sau vào Gemfile và chạy bundle install
gem "grape"
Tạo một Employee model cho phương thức tạo/sửa/xóa/đọc cơ bản
Bên trong emp_api/app/ tạo 1 forder api
Bên trong thư mục emp_api/app/api tạo một forder employee, trong emp_api/app/api/employee tạo 1 file data.rb, file data.rb này sẽ truy cập vào Employee model
Bên trong forder emp_api/app/api/ tạo 1 file api.rb, là nơi mà sẽ gắn kết các lớp được định nghĩa trong emp_api/app/api/employee/data.rb.
2. Modularizing cấu trúc thư mục API
Như đã nói ở trên thay thế các file API thành app/api, thư mục cần được thêm vào load/autoload paths => Cài đặt trong config/application.rb:
require File.expand_path('../boot', __FILE__)
require 'rails/all'
Bundler.require(*Rails.groups)
moduleEmpApi
classApplication < Rails::Application
## Newly Added code to set up the api code
config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
end
end
Creating the API. Ví dụ tạo API endpoint để lấy thông tin chi tiết của tất cả employee. Mở file app/api/employee/data.rb và tạo module class như sau :
module Employee
class Data < Grape::API
resource :employee_data do
desc "List all Employee"
get do
EmpData.all
end
end
end
end
Truy nhập Employee::Data class bên trong API class, sử dụng mount để tạo Employee::Data class có thể truy cập được bên trong API class.
Mở #app/api/api.rb thêm mount Employee::Data
class API < Grape::API
prefix 'api'
version 'v1', using: :path
mount Employee::Data
end
3. Mounting API under rails routes
Thêm vào app/config/routes.rb
Rails.application.routes.draw do
mount API => "/"
end
4. Customize JSON API Errors
Chỉ địnhapi raise errors và tùy chỉnh chúng response về định dạng khi có ngoại lệ
# app/api/error_formatter.rb
module API
module ErrorFormatter
def self.call message, backtrace, options, env
{response_type: "error", response: message}.to_json
end
end
end
hoặc nhúng module này vào bên trong API::Root
# app/api/root.rb
module API
class Root < Grape::API
#…
error_formatter :json, API::ErrorFormatter
#…
end
end
5. Securing API
5.1. HTTP Basic authentication
Thêm xác thực cơ bản vào API::Root và nó có tác dụng cho tất cả các phiên bản của API:
# app/api/root.rb
module API
class Root < Grape::API
#…
http_basic do |email, password|
user = User.find_by_email(email)
user && user.valid_password?(password)
end
#…
end
end
Yêu cầu API bằng các thông tin http auth cơ bản:
curl http://localhost:3000/api/products -u "admin:secret"
5.2. Xác thực sử dụng email và password
Grape cung cấp cho chúng ta before block để có thể xác thực trước khi truy cập
# app/api/root.rb
module API
class Root < Grape::API
#…
before do
error!(“401 Unauthorized”, 401) unless authenticated
end
helpers do
def authenticated
user = User.find_by_email(params[:email])
user && user.valid_password?(params[:password])
end
end
#…
end
end
6. Chạy tới action bằng lệnh trên terminal
Đánh lệnh sau vào terminal :
curl http://localhost:3000/api/v1/employee_data.json
=> result : [ ]
6.1. Sử dụng curl để post 1 request tới endpoint (create)
Thêm đoạn code sau vào app/api/employee/data.rb
desc "create a new employee"
## This takes care of parameter validation
params do
requires :name, type: String
requires :address, type:String
requires :age, type:Integer
end
## This takes care of creating employee
post do
EmpData.create!({
name:params[:name],
address:params[:address],
age:params[:age]
})
end
Trên terminal:
curl http://localhost:3000/api/v1/employee_data.json -d name="hoa nguyen" -d address="Ha Noi" -d age="25"
=> result : {“id”:1,”name”:”hoa nguyen”,”address”:”Ha Noi”,”age”:25,”created_at”:”2015-01-31T11:55:00.356Z”,”updated_at”:”2015-01-31T11:55:00.356Z”}
Kiểm tra employee vừa tạo bằng lệnh:
curl http://localhost:3000/api/v1/employee_data.json
=> result hiện trên terminal : [{"id":1,"name":"hoa nguyen","address":"Ha Noi","age":25,"created_at":"2015-01-31T11:55:00.356Z","updated_at":"2015-01-31T11:55:00.356Z"}]
6.2. Xóa 1 bản ghi
Làm tương tự như hàm create, thêm đoạn code sau vào trong # app/api/employee/data.rb
# app/api/employee/data.rb
desc "delete an employee"
params do
requires :id, type: String
end
delete ':id' do
EmpData.find(params[:id]).destroy!
end
Trên terminal thêm dòng sau :
curl -X DELETE http://localhost:3000/api/v1/employee_data/1.json
=> result: {“id”:1,”name”:”hoa nguyen”,”address”:”Ha Noi”,”age”:25,”created_at”:”2015-01-31T11:55:00.356Z”,”updated_at”:”2015-01-31T11:55:00.356Z”}
Đánh lệnh sau vào terminal :
curl http://localhost:3000/api/v1/employee_data.json
=> result : [ ]
6.3. Update
Thêm đoạn sau vào #app/api/employee/data.rb để tạo bản ghi:
# app/api/employee/data.rb
desc "update an employee address"
params do
requires :id, type: String
requires :address, type:String
end
put ':id' do
EmpData.find(params[:id]).update({
address:params[:address]
})
end
Restart server và đánh lệnh sau vào :
curl http://localhost:3000/api/v1/employee_data.json -d name="hoa nguyen" -d address="Ha Noi" -d age="25"
=> result : {“id”:2,”name”:”hoa nguyen”,”address”:”Ha Noi”,”age”:25,”created_at”:”2015-01-31T12:02:01.485Z”,”updated_at”:”2015-01-31T12:02:01.485Z”}
Sử dụng lệnh sau để update name của employee:
curl -X PUT http://localhost:3000/api/v1/employee_data/2.json -d name=”hoa” -d address=”Dan Phuong”
=> result : true
Đánh lệnh sau vào terminal :
curl http://localhost:3000/api/v1/employee_data.json
=> result : [{"id":2,"name":"hoa nguyen","address":"Dan Phuong","age":25,"created_at":"2015-01-31T12:02:01.485Z","updated_at":"2015-01-31T12:03:59.679Z"}]
III. Lời kết
Ruby on Rails API có rất nhiều tính năng hay và thú vị để tìm hiểu nhưng trong phạm vi bài báo cáo chỉ có thể nói sơ lược qua về API và engine điển hình của nó là Grape và cách tạo một API đơn giản với Grape.
Source demo : https://github.com/nguyenhoa/emp_api
Để có thể tìm hiểu kỹ các bạn có thể tham khảo một số trang web sau :
https://github.com/intridea/grape http://www.theodinproject.com/ruby-on-rails/apis-and-building-your-own https://www.amberbit.com/blog/2014/2/19/building-and-documenting-api-in-rails/ https://developer.github.com/guides/getting-started/#authentication http://www.sitepoint.com/build-great-apis-grape/ http://funonrails.com/2014/03/building-restful-api-using-grape-in-rails/
All rights reserved
