Using Sinatra to Build REST APIs in Ruby

Using
Sinatra
to
Build

REST
APIs
in
Ruby

James
Higginbotham

API
Architect

@launchany

Sinatra
is
a
DSL
for
quickly

crea<ng
web
applica<ons
in

Ruby

# hi.rb
require 'rubygems’
require 'sinatra'
get '/' do
'Hello world!’
end
$ gem install sinatra
$ ruby hi.rb
== Sinatra has taken the stage ...
>> Listening on 0.0.0.0:4567
$ curl http://0.0.0.0:4567
Hello World

HOW
DOES
SINATRA
WORK?

Rou?ng:
Verb
+
PaCern
+
Block

post ’/' do
.. block ..
end

Rou?ng:
Named
Params

get '/:id' do
model = MyModel.find( params[:id] )
...
end

Rou?ng:
Splat
Support

get '/say/*/to/*' do
# matches /say/hello/to/world
params['splat'] # => ["hello", "world"]
...
end
get '/download/*.*' do
# matches /download/path/to/file.xml
params['splat'] # => ["path/to/file", "xml"]
...
end

Rou?ng:
Regex
Support

get /A/hello/([w]+)z/ do
"Hello, #{params['captures'].first}!”
...
end

Rou?ng:
Op?onal
Parameters

get '/posts.?:format?' do
# matches "GET /posts" and
# any extension "GET /posts.rss", "GET /posts.xml" etc.
end

Rou?ng:
URL
Query
Parameters

get '/posts' do
# matches "GET /posts?title=foo&author=bar"
title = params['title']
author = params['author']
# uses title and author variables;
# query is optional to the /posts route
End

Rou?ng:
Condi?onal
Matching

get '/', :host_name => /^admin./ do
"Admin Area, Access denied!"
end
get '/', :provides => 'html' do
haml :index
end
get '/', :provides => ['rss', 'atom', 'xml'] do
builder :feed
end

Rou?ng:
Custom
Condi?ons

set(:probability) { |value| condition { rand <= value } }
get '/win_a_car', :probability => 0.1 do
"You won!"
end
get '/win_a_car' do
"Sorry, you lost."
End

Returning
Results

# 1. String containing the body and default code of 200
get '/' do
'Hello world!’
end
# 2. Response code + body
get '/' do
[200, 'Hello world!’]
end
# 3. Response code + headers + body
get '/' do
[200, {'Content-Type' => 'text/plain'}, 'Hello world!’]
end

Hello
World
with
Rack

# hello_world.rb
require 'rack'
require 'rack/server’
class HelloWorldApp
def self.call(env)
[200, {}, 'Hello World’]
end
end
Rack::Server.start :app => HelloWorldApp

Rack
env

# hello_world.rb
require 'rack'
require 'rack/server’
class HelloWorldApp
def self.call(env)
[200, {},
"Hello World. You said: #{env['QUERY_STRING']}"]
end
end
Rack::Server.start :app => HelloWorldApp

Typical
env

{
"SERVER_SOFTWARE"=>"thin 1.4.1 codename Chromeo",
"SERVER_NAME"=>"localhost",
"rack.input"=>#<StringIO:0x007fa1bce039f8>,
"rack.version"=>[1, 0],
"rack.errors"=>#<IO:<STDERR>>,
"rack.multithread"=>false,
"rack.multiprocess"=>false,
"rack.run_once"=>false,
"REQUEST_METHOD"=>"GET",
"REQUEST_PATH"=>"/favicon.ico",
"PATH_INFO"=>"/favicon.ico",
"REQUEST_URI"=>"/favicon.ico",
"HTTP_VERSION"=>"HTTP/1.1",
"HTTP_HOST"=>"localhost:8080",
"HTTP_CONNECTION"=>"keep-alive",
"HTTP_ACCEPT"=>"*/*”,
...

Typical
env
(con’t)

...
"HTTP_USER_AGENT"=>
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4)
AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.47
Safari/536.11",
"HTTP_ACCEPT_ENCODING"=>"gzip,deflate,sdch",
"HTTP_ACCEPT_LANGUAGE"=>"en-US,en;q=0.8",
"HTTP_ACCEPT_CHARSET"=>"ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"HTTP_COOKIE"=> "_gauges_unique_year=1;
_gauges_unique_month=1",
"GATEWAY_INTERFACE"=>"CGI/1.2",
"SERVER_PORT"=>"8080",
"QUERY_STRING"=>"",
"SERVER_PROTOCOL"=>"HTTP/1.1",
"rack.url_scheme"=>"http",
"SCRIPT_NAME"=>"",
"REMOTE_ADDR"=>"127.0.0.1",
...
}

The
Rack::Request
Wrapper

class HelloWorldApp
def self.call(env)
request = Rack::Request.new(env)
request.params # contains the union of GET and POST
params
request.xhr? # requested with AJAX
require.body # the incoming request IO stream
if request.params['message']
[200, {}, request.params['message']]
else
[200, {}, 'Say something to me!']
end
end
end

Rack
Middleware

u  Rack
allows
for
chaining
mul?ple
call()

methods

u  We
can
do
anything
we
want
within
each
call()

u  This
includes
separa?ng
behavior
into

reusable
classes
(e.g.
across
Sinatra
and
Rails)

u  SRP
(Single
Responsibility
Principle)

– Each
class
has
a
single
responsibility

– Our
app
is
composed
of
mul?ple
classes
that
each

do
one
thing
well

Rack::Builder
for
Middleware

# this returns an app that responds to call cascading down
# the list of middlewares.
app = Rack::Builder.new do
use Rack::Etag # Add an ETag
use Rack::ConditionalGet # Support Caching
use Rack::Deflator # GZip
run HelloWorldApp # Say Hello
end
Rack::Server.start :app => app
# Resulting call tree:
# Rack::Etag
# Rack::ConditionalGet
# Rack::Deflator
# HelloWorldApp

Using
the
Rackup
Command

u  Combines
all
of
these
concepts
into
a
config

u  Will
start
a
web
process
with
your
Rack
app

u  Central
loca?on
for
requires,
bootstrapping

u  Enables
middleware
to
be
configured
as
well

u  Default
filename
is
config.ru

u  Used
to
bootstrap
Rails

Using
Rackup

# config.ru
# HelloWorldApp defintion
# EnsureJsonResponse defintion
# Timer definition
use Timer
use EnsureJsonResponse
run HelloWorldApp
$ rackup –p 4567

Using
Mul?ple
Sinatra
Apps

u  Rackup
allows
for
moun?ng
mul?ple
Sinatra

Apps

u  This
allows
for
more
modular
APIs

u  Recommend
one
Sinatra
app
per
top-‐level

resource

Moun?ng
Mul?ple
Sinatra
Apps

# config.ru
require 'sinatra'
require 'app/auth_api'
require 'app/users_api'
require 'app/organizations_api'
map "/auth" do
run AuthApi
end
map "/users" do
run UsersApi
end
map "/organizations" do
run OrganizationsApi
end

Important:
Require
!=
Automa?c

u  Must
manage
your
own
requires

u  No
free
ride
(like
with
Rails)

u  This
means
order
of
requires
is
important!

Mul?ple
API
Design
Choices

u  RPC-‐based

– Uses
HTTP
for
transport
only

– Endpoints
are
not
unique,
only
the
payload

– No
HTTP
caching
available

– e.g.
POST
/getUserDetails,
POST
/createUser

u  Resource-‐based

– Unique
URLs
for
resources
and
collec?ons

– HTTP
caching
available

– e.g.
GET
/users/{userId}
and
GET
/users

Hypermedia
REST

u  An
architectural
style,
with
constraints

u  A
set
of
constraints,
usually
on
top
of
HTTP

u  Not
a
standard;
builds
on
the
standard
of

HTTP

u  Mul?ple
content
types
(e.g.
JSON,
XML,
CSV)

u  The
response
is
a
representa?on
of
the

resource
state
(data)
plus
server-‐side
state
in

the
form
of
ac<ons/transi<ons
(links)

BUILDING
AN
API
USING
SINATRA

Resource
Lifecycle
using
Sinatra

get '/users' do
.. list a resource collection (and search) ..
end
get '/users/:id' do
.. resource instance details ..
end
post '/users' do
.. create new resource ..
end
put '/users/:id' do
.. replace resource ..
End
delete ’/users/:id' do
.. annihilate resource ..
end

List
Resources
Example

get '/users' do
# 1. capture any search filters using params[]
email_filter = params[:email]
# 2. build query and fetch results from database
if email_filter
users = User.where( email: email_filter ).all
else
users = User.all
# 3. marshal results to proper content type (e.g. JSON)
[200, users.to_json]
end

List
Resources
Example

get '/users' do
# 1. capture any search filters using params[]
email_filter = params[:email]
# 2. build query and fetch results from database
if email_filter
users = User.where( email: email_filter ).all
else
users = User.all
# 3. marshal results to proper content type (e.g. JSON)
[200, users.to_json]
# Q: Which ORM should we use with Sinatra?
# Q: Can we customize the results format easily?
end

Selec?ng
an
ORM

u  Ac?veRecord

u  DataMapper

u  Sequel
(my
favorite)

– Flexible
as
it
supports
Datasets
and
Models

Sequel
Datasets
Example

require 'sequel'
DB = Sequel.sqlite # memory database
DB.create_table :items do
primary_key :id
String :name
Float :price
end
items = DB[:items] # Create a dataset
items.insert(:name => 'abc', :price => rand * 100)
items.insert(:name => 'def', :price => rand * 100)
items.insert(:name => 'ghi', :price => rand * 100)
puts "Item count: #{items.count}"
puts "The average price is: #{items.avg(:price)}”

Sequel
Model
Example

require 'sequel'
DB = Sequel.sqlite # memory database
class Post < Sequel::Model
end
post = Post[123]
post = Post.new
post.title = 'hello world'
post.save

Select
a
Marshaling
Library

u  Ac?veModel::Serializers
(AMS)

– Works
with
Kaminari
and
WillPaginate

– Supported
by
Rails
core
team

– One-‐way
JSON
genera?on
only

u  Roar+Representable
(my
favorite)

– Works
with
and
without
Rails

– Bi-‐direc?onal
marshaling

– Supports
JSON,
XML,
YAML,
hash

Representable

module SongRepresenter
include Representable::JSON
property :title
property :track
collection :composers
end
class Song < OpenStruct
end
song = Song.new(title: "Fallout", track: 1)
song.extend(SongRepresenter).to_json
> {"title":"Fallout","track":1}
song = Song.new.extend(SongRepresenter).from_json(%
{ {"title":"Roxanne"} })
> #<Song title="Roxanne">

Roar
+
Representable

module SongRepresenter
include Roar::JSON
include Roar::Hypermedia
property :title
property :track
collection :composers
link :self do
"/songs/#{title}"
end
end
song = Song.new(title: "Fallout", track: 1)
song.extend(SongRepresenter).to_json
> {"title":"Fallout","track":1,"links":
[{"rel":"self","href":"/songs/Fallout"}]}"

Tools
for
Tes?ng
Your
API

u  Unit
–
RSpec

– Models,
helpers

u  Integra?on
–
RSpec

– Make
HTTP
calls
to
a
running
Sinatra
process

– Controller-‐focused

u  Acceptance/BDD
–
RSpec,
Cucumber

– Make
HTTP
calls
to
a
running
Sinatra
process

– Use-‐case/story
focused

MATURING
YOUR
SINATRA
APPS

Addi?onal
Gems

u  faraday
–
HTTP
client
with
middleware
for

tes?ng
and
3rd
party
API
integra?on

u  xml-‐simple
–
Easy
XML
parsing
and
genera?on

u  faker
–
Generates
fake
names,
addresses,
etc.

u  uuidtools
–
uuid
generator
when
incremen?ng

integers
aren’t
good
enough

u  bcrypt
–
Ruby
binding
for
OpenBSD
hashing

algorithm,
to
secure
data
at
rest

Addi?onal
Gems
(part
2)

u  rack-‐conneg
–
Content
nego?a?on
support

get '/hello' do
response = { :message => 'Hello, World!' }
respond_to do |wants|
wants.json { response.to_json }
wants.xml { response.to_xml }
wants.other {
content_type 'text/plain'
error 406, "Not Acceptable"
}
end
end
curl -H "Accept: application/json" http://localhost:4567/
hello

Addi?onal
Gems
(part
3)

u  hirb
–
Console
formaing
of
data
from
CLI,

Rake
tasks

irb>> Tag.last
+-----+-------------------------+-------------+
| id | created_at | description |
+-----+-------------------------+-------------+
| 907 | 2009-03-06 21:10:41 UTC | blah |
+-----+-------------------------+-------------+
1 row in set

Reloading
with
Shotgun
Gem

u  No
automa?c
reload
of
classes
with
Sinatra

u  Instead,
use
the
shotgun
gem:

u  Note:
Only
works
with
Ruby
MRI
where
fork()

is
available
(POSIX)

$ gem install shotgun
$ shotgun config.ru

Puma
+
JRuby

u  Ruby
MRI
is
geing
beCer

u  JVM
is
faster
(2-‐5x),
very
mature
(since
1997)

u  High
performance
garbage
collectors,
na?ve

threading,
JMX
management
extensions

u  JDBC
libraries
very
mature
and
performant
for

SQL-‐based
access

u  Puma
is
recommended
over
unicorn
for
JRuby

From
Sinatra
to
Padrino

u  Padrino
provides
Rails-‐like
environment
for

Sinatra

u  Build
in
Sinatra,
move
to
Padrino
when

needed

u  Generators,
pluggable
modules,
admin

generator

Resources

u  Sinatra
Docs:

hCp://www.sinatrarb.com/intro.html

u  Introduc?on
to
Rack:

hCp://hawkins.io/2012/07/rack_from_the_beginning/

u  Sequel
Gem:

hCps://github.com/jeremyevans/sequel

u  Roar/Representable:

hCps://github.com/apotonick/roar

hCps://github.com/apotonick/representable

Thanks
Ya’ll

James
Higginbotham

james@launchany.com

hCp://launchany.com

@launchany

Design
Beau?ful
APIs:

hCp://TheApiDesignBook.com

Using Sinatra to Build REST APIs in Ruby

More Related Content

What's hot (20)

Similar to Using Sinatra to Build REST APIs in Ruby (20)

More from LaunchAny (20)

Recently uploaded (20)

Using Sinatra to Build REST APIs in Ruby