Finding Restfulness - Madrid.rb April 2014

Finding Restfulness
Sam Lown, April 2014

Who am I?
• CTO and co-founder of Cabify.
• Freelancer for many years before.
• Obsessed with ﬁnding simple, elegant solutions
to problems.

What am I going to
talk about?

I’m not going to talk about
creating REST APIs in Rails
(although there is some mixed in)

For that, checkout
Javier Ramirez’s talks:
Google: “Javier Ramirez REST”

I’m going show you
A brand new way of
creating REST APIs in
Ruby!

REST is about Resources
that re-use as much from
HTTP as possible.
and just in case, Sam’s summary of REST:

“something was
irritating Sam”

Rails Controllers
Speciﬁcally:

They started to feel 
out of place 
with the problems I was solving.

Take the following
basic controller…

class PostController < ApplicationController!
respond_to :html, :json!
!
def index!
@posts = Post.all!
respond_with(@posts)!
end!
!
def show!
@post = Post.find(params[:id])!
respond_with(@post)!
end!
!
def new!
@post = Post.new!
end!
!
def create!
@post = Post.create(params[:post])!
end!
!
def edit!
end!
!
def update!
end!
!
def delete!
@post.destroy!
end!
end
posts_controller.rb:
routes.rb:
PostApp::Application.routes.draw do!
resources :posts!
end

1st irritant: too many methods
!
I only need JSON!"
!
(easy to ﬁx…)

respond_to :json!
!
def index!
@posts = Post.all!
end!
!
def show!
end!
!
def create!
end!
!
def update!
end!
!
def delete!
@post.destroy!
end!
end
routes.rb:
resources :posts!
end

2nd irritant: 
adding sub-actions

respond_to :json!
!
def index!
@posts = Post.all!
end!
!
def show!
end!
!
def create!
end!
!
def update!
end!
!
def latest!
@posts = Post.order_by(:created_at)!
end!
!
def last!
@post = Post.last!
end!
!
def delete!
@post.destroy!
end!
end
routes.rb:
resources :posts do!
member do!
get :last!
end!
collection do!
get :latest!
end!
end!
end
Always felt a bit 
“stuck on”

3rd irritant: 
parameter namespaces

class Post extends Backbone.Model!
!
paramRoot: ‘post’!
!
url: ->!
“/posts/” + @id!
!
parse: (res) ->!
if res.post?!
res.post!
else!
res
Coffeescript Model:
{!
“post”: {!
“title”: “Example post”,!
“created_at”: “2014-04-21T16:10:00Z”!
}!
}
JSON from server:
Backbone expects urls to 
return data directly!

4th irritant: 
query, path, and params,
all mixed up

Request: 
PUT /posts/1234?draft=false 
 
Body:!
{!
“post”: { …. }!
}!
!
Action:"
def update!
unless params[:draft]!
@post.update_attributes(params[:post])!
end!
end 
Different data, with"
different meanings,"
all in the same place?

5th irritant: 
collection and element 
confusion!
(and probably the most irritating)

Take the Wikipedia REST Page:
Resource GET PUT POST DELETE
Collection URI 
/resources
List
collection
Replace
collection
Create 
new 
element
Delete
collection
Element 
URI 
/resources/id
Retrieve
element
Replace
element
not used
Delete
element

Seriously, what?
Resource GET PUT POST DELETE
Collection URI 
/resources
List
collection
Replace
collection
Create 
new 
element
Delete
collection
Element 
URI 
/resources/id
Retrieve
element
Replace
element
not used
Delete
element

Root of irritations:
Rails controllers were
designed for web views,
not APIs!

Are there any other ways
of creating APIs in Ruby?
So, I thought to myself,

gem install rails-api
Rails API

“Rails::API is a subset of a normal Rails
application, created for applications
that don't require all functionality that a
complete Rails application provides.”
https://github.com/rails-api/rails-api

Rails without views.
Translation:
Cool, buy not really what we’re looking for.

“Grape allows you to build lightweight
APIs with Ruby when you don't need the
heavy lifting power of large frameworks
like Rails. It's a REST-like API micro-
framework built to complement existing
web application frameworks by providing
a simple DSL to easily provide APIs.”
http://intridea.github.io/grape/

But whats that about
DSLs and REST-like?
sounds okay…
we need a code sample…

module Twitter!
class API < Grape::API!
!
version 'v1', using: :header, vendor: 'twitter'!
format :json!
!
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."!

Crap, it doesn’t ﬁt on a
single slide…

Probably because it tries
to do everything in a
single Ruby ﬁle.
Not a good start.

Let the nitpicking feature
identiﬁcation start…

module Twitter!
class API < Grape::API!
!
version 'v1', using: :header, vendor: 'twitter'!
format :json!
!
helpers do!
def current_user!
@current_user ||= User.authorize!(env)!
end!
!
def authenticate!!
error!('401 Unauthorized', 401) unless current_user!
end!
end!
Versioning
Helpers
Error handling

resource :statuses do!
!
desc "Return a public timeline."!
get :public_timeline do!
Status.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
Resources, kind of
Strange rack like 
descriptions
Parameter ﬁltering
Path elements?
HTTP 
Method

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!
returned object 
converted to JSON
more parameter ﬁltering
wtf? more parameter ﬁltering!

Grape does some
cool stuff!
don’t get me wrong

Google
Google
Google
Google
(can’t actually remember what)

webmachine for Ruby
gem install webmachine

“webmachine-ruby is a port of Webmachine,
which is written in Erlang. The goal of both
projects is to expose interesting parts of the
HTTP protocol to your application in a
declarative way. This means you are less
concerned with handling requests directly and
more with describing the behaviour of the
resources that make up your application.”
https://github.com/seancribbs/webmachine-ruby

Okay, this sounds
more like it!

Sam likes things that
are totally different!
let’s have a look at the code

require 'webmachine'!
class MyResource < Webmachine::Resource!
def to_html!
"<html><body>Hello, world!</body></html>"!
end!
end!
!
# Start a web server on localhost!
MyResource.run
Interesting, “Resource”
Getting started:

Webmachine.application.routes do!
add ['myresource'], MyResource!
end!
!
# Start a web server on localhost!
Webmachine.application.run
Simple routing to speciﬁc resources!
Routing:

HTTP features are exposed via
callbacks:
Webmachine::Resource::Callbacks

After this point examples
started to become a bit
scarce…

A few Resource callbacks:
is_authorized? 
forbidden? 
is_conflict?!
allow_missing_post?!
content_types_accepted!
last_modified!
generate_etag!
languages_provided
etc. etc.

Callbacks in action:
require 'webmachine'!
class MyResource < Webmachine::Resource!
!
def is_authorized?!
request.query[‘name’] == ‘sam’!
end!
!
def to_html!
"<html><body>Hello, world!</body></html>"!
end!
(Disclaimer, I’m not actually sure if the 
request query bit is correct)

To be honest, it all
looked a bit confusing.

Sam’s new theory:
“If you can’t get it to do
anything useful within a day,
its too freeking complicated”

But maybe I can do
something about this…

I like the idea of 
resources 
being the focus of requests.

I want my query, path,
and body parameters 
separate.

I like the funky
callback stuff.

I want to be as close to 
HTTP and REST 
as possible.

I still thought I could do
something about this…

“Restfulness is a Ruby library that helps
create REST based APIs to your
services. The focus is placed on
performing HTTP actions on
resources via speciﬁc routes, as
opposed to assigning routes and HTTP
actions to methods or blocks of code”
https://github.com/samlown/restfulness

class MyAPI < Restfullness::Application!
routes do!
scope 'api' do!
add 'post', Posts::ItemResource!
add ‘posts', Posts::ListResource do!
add ‘favourite', Posts::FavResource!
end!
end!
end!
end
Routes build paths"
that point to Resources!

Paths recognised from routes
/api/post 
/api/post/1234!
/api/posts!
/api/posts/1234!
/api/posts/favourite!
/api/posts/favourite/1234
Convention: each path allows"
optional ID on end!

add 'post', Posts::ItemResource do!
add :post_id, ‘comments’,!
Posts::CommentsResource
end!
Symbols in routes catch anything!
Interpolation
/api/post 
/api/post/1234!
/api/post/1234/comments!
/api/post/1234/comments/1234

Route Rules
• Route entries form paths when joined with ‘/‘
• Order is important.
• Strings are matched.
• Symbols match anything, and are accessible
as path attributes.
• Every path gets an :id parameter at the end,
that may or may not have a null value.
• Scopes avoid repeating path entries.

And thats it.
Routing in Restfulness
is incredibly simple

class ProjectResource < Restfulness::Resource!
!
def get!
project!
end!
!
def patch!
project.update(request.params)!
end!
!
protected!
!
def project!
@project ||= Project.find(request.path[:id])!
end!
!
end
HTTP methods

The object returned is converted to JSON
def get!
project!
end!
# Somewhere inside Restfulness!
result = resource.send(method)!
response.body = 
MultJson.dump(result)

Resource Methods
get!
head 
post!
patch!
put!
delete!
options

Method not deﬁned? 
Don’t expect a response!
curl -v —X OPTIONS https://cabify.com/api/regions!
 
< HTTP/1.1 204 No Content 
< Allow: GET, OPTIONS!
!
!
curl -v —X POST https://cabify.com/api/regions!
 
< HTTP/1.1 405 Method Not Allowed

request.uri # URI object!
request.headers # Hash, Symbol => Val!
!
request.path.to_s # '/project/123456'!
request.path # ['project', '123456']!
request.path[:id] # '123456'!
request.path[0] # ‘project'!
!
request.query # {:page => 1}!
request.query[:page] # 1!
!
request.body # "{'key':'value'}"!
!
request.params # {'key' => 'value'}

def get!
if project.is_a_teapot?!
response.status = 418!
response.headers[‘X-Tea-Pot’] = ‘true’!
end!
project!
end

class ProjectResource < Restfulness::Resource!
!
def exists?!
!project.nil?!
end!
!
def last_modified!
project.updated_at.to_s!
end!
!
def get!
project!
end 
 
………!
Callbacks return booleans, 
or values to return to client.

Callbacks control ﬂow.
!
If a boolean callback returns false,
an error is raised and instantly
stops execution of the Resource!
(error handling coming up!)

Supported callbacks
exists?!
authorized? 
allowed?!
last_modified!
etag
(never needed more!)

class ProjectResource < ApplicationResource!
!
def patch!
unless project.update_attributes(request.params)!
forbidden!(project)!
end!
project!
end!
!
end!
Fail? 
Halt and provide 403 response

Supported responses:
not_modified!!
bad_request! 
unauthorized!!
forbidden!!
resource_not_found!!
request_timeout!!
conflict!!
gone!!
unprocessable_entity!

Your favourite error method not there?
def im_a_teapot!(payload = “”)!
error!(418, payload)!
end
Add it!

class ApplicationResource < Restfulness::Resource!
!
def error!(status, payload = "", opts = {})!
case payload!
when ActiveRecord::Base!
payload = {!
:errors => payload.errors.full_messages!
}!
end!
super(status, payload, opts)!
end!
end!
Yes! Wrap, and provide all
errors in the same format!

Restfulness runs on Rack,
so you can easily plug it
into existing projects (Rails)
or run it on its own (Sinatra)

Standalone
$ vi config.ru!
!
require 'my_app'!
run MyApp.new!
!
$ rackup

Or as part of a Rails project
# In Rails application.rb!
config.autoload_paths += [!
“#{config.root}/app/resources”, 
“#{config.root}/app/apis”!
]!
!
# In Rails Routes!
YourRailsApp::Application.routes.draw do !
mount MyApi.new => '/api'!
…!
This way you get auto-reloading

I hope you too ﬁnd 
Restfulness 
:-)
that’s about all there is to it!
https://github.com/samlown/restfulness

?
(for 10€ off you next Cabify ride: “MADRIDRB”)

Finding Restfulness - Madrid.rb April 2014

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Finding Restfulness - Madrid.rb April 2014 (20)

Recently uploaded (20)

Finding Restfulness - Madrid.rb April 2014