Building an API in Rails without Realizing It

Rails APIs
Monday, February 25, 13

@markbates

http://www.metacasts.tv
CONFOO2013


e b APIs
Rails
W

you’re probably
doing it wrong


Don’t Panic!

most APIs are an
after thought


we can prevent
that!


3 simple rules for
building an API


1. consume your
own API


2. document your
API


3. version your
API


building the API


Service Oriented
Architecture


SOA Pros


SOA Pros

• Scales Easily


SOA Pros

• Scales Easily

• Separate Concerns/Very Clean


SOA Pros

• Scales Easily


• Can be easier to maintain


SOA Pros

• Scales Easily



• Solid Architecture


SOA Pros

• Scales Easily



• Solid Architecture

• Easier to refactor/rebuild


SOA Cons


SOA Cons

• Can be more difﬁcult to maintain


SOA Cons


• More complex deploys


SOA Cons



• Managing several applications


SOA Cons




• Potential for ‘out-of-sync’ apps


SOA Cons




• Potential for ‘out-of-sync’ apps

• More difﬁcult to test integration


API Client


Client

API

Client


Client

API Client

Client


Client
Service 1

Service 2 Client

Service 3
Client


a quick detour


Rails encourages
poor API design!


#
POST
/todos

#
POST
/todos.json

def
create
class
TodosController
<
ApplicationController

@todo
=
Todo.new(params[:todo])

#
GET
/todos

#
GET
/todos.json

respond_to
do
|format|

def
index

if
@todo.save

@todos
=
Todo.all

format.html
{
redirect_to
@todo,
notice:
'Todo
was
successfully
created.'
}

format.json
{
render
json:
@todo,
status:
:created,
location:
@todo
}

respond_to
do
|format|

else

format.html
#
index.html.erb

format.html
{
render
action:
"new"
}

format.json
{
render
json:
@todos
}

format.json
{
render
json:
@todo.errors,
status:
:unprocessable_entity
}

end

end

end

end

end

#
GET
/todos/1

#
GET
/todos/1.json

#
PUT
/todos/1

def
show

#
PUT
/todos/1.json

@todo
=
Todo.find(params[:id])

def
update

@todo
=

respond_to
do
|format|

format.html
#
show.html.erb

respond_to
do
|format|

format.json
{
render
json:
@todo
}

if
@todo.update_attributes(params[:todo])

end

format.html
{
redirect_to
@todo,
notice:
'Todo
was
successfully
updated.'
}

end

format.json
{
head
:no_content
}

else

#
GET
/todos/new

format.html
{
render
action:
"edit"
}

#
GET
/todos/new.json

format.json
{
render
json:
@todo.errors,
status:
}

def
new

end

@todo
=
Todo.new

end

end

respond_to
do
|format|

format.html
#
new.html.erb

#
DELETE
/todos/1

format.json
{
render
json:
@todo
}

#
DELETE
/todos/1.json

end

def
destroy

end

@todo
=

@todo.destroy

#
GET
/todos/1/edit

def
edit

respond_to
do
|format|

@todo
=

format.html
{
redirect_to
todos_url
}

end

format.json
{
head
:no_content
}

end

end
end


Don’t Scaffold!


class
TodosController
<

def
index

@todos
=
Todo.all

end

def
show

@todo
=

end

def
new

@todo
=
Todo.new

end

def
edit

@todo
=

end

def
create

@todo
=

if
@todo.save

redirect_to
@todo,
notice:
'Todo
was
successfully
created.'

else

render
action:
"new"

end

end

def
update

@todo
=

if

redirect_to
@todo,
notice:
'Todo
was
successfully
updated.'

else

render
action:
"edit"

end

end

def
destroy

@todo
=

@todo.destroy

redirect_to
todos_path,
notice:
'Todo
was
successfully
destroyed.'

end
end


class
TodosController
<

inherit_resources
end


Inherited Resources
https://github.com/josevalim/inherited_resources


class
Api::V1::TodosController
<

respond_to
:json

before_filter
do

request.format
=
:json

end

def
index

@todos
=
Todo.all

respond_with
@todos

end

def
show

@todo
=

respond_with
@todo

end

def
create

@todo
=

if
@todo.save

respond_with
@todo

else

render
json:
@todo.errors,
status:

end

end

def
update

@todo
=

if

respond_with
@todo

else

render
json:
@todo.errors,
status:

end

end

def
destroy

@todo
=

@todo.destroy

head
:no_content

end
end


version your API!
Api::V1::TodosController
/api/v1/todos


i prefer URL
versioning


others prefer
header versioning


just pick one and
stick with it!


SOA Review


SOA Review

• We’ve cleaned up our code


SOA Review


• We know the API Works


SOA Review


• We know the API Works

• We’re now in a good place to scale


consuming the API


don’t use
Rails views


JavaScript

Cross-origin
Resource Sharing


rack-cors
https://github.com/cyu/rack-cors


module
YourApp

class
Application
<
Rails::Application

#
...

config.middleware.use
Rack::Cors
do

allow
do

origins
'*'

resource
'*',
headers:
:any,

methods:
[:get,
:post,
:put,
:delete,
:options]

end

end

end


JavaScript Pros


JavaScript Pros

• Scales Easily/Pushes processing to client side


JavaScript Pros




JavaScript Pros




• “Responsive/Native” feel for clients


JavaScript Pros




• “Responsive/Native” feel for clients

• Easily consumes your API


JavaScript Cons


JavaScript Cons

• Multiple languages (backend/front-end)


JavaScript Cons


• Difﬁcult to test integration


JavaScript Cons



• JavaScript


JavaScript Cons



• JavaScript

• Paradigm shift in architecture


JavaScript Cons
• Can be more difﬁcult to maintain • Accessibility issues



• JavaScript



JavaScript Cons

• Multiple languages (backend/front-end) • SEO concerns


• JavaScript



JavaScript Cons

• Multiple languages (backend/front-end) • SEO concerns

• Difﬁcult to test integration • !!Internet Explorer!!

• JavaScript



pick a
framework

don’t just
use jQuery

the big
three

Backbone.js

http://backbonejs.org/


ember

http://emberjs.com/


Angular.js

http://angularjs.org/


i can’t use
JavaScript


2 approaches

“compiled” sites


build your own
API library (and
open source it!)

class
TodosController
<

def
index

@todos
=
ApiLib::Todo.all

end

def
show

@todo
=
ApiLib::Todo.find(params[:id])

end

def
new

@todo
=
ApiLib::Todo.new

end

def
edit

@todo
=

end

def
create

@todo
=
ApiLib::Todo.new(params[:todo])

if
@todo.save

redirect_to
@todo,
notice:
'Todo
was
successfully
created.'

else

render
action:
"new"

end

end

def
update

@todo
=

if

redirect_to
@todo,
notice:
'Todo
was
successfully
updated.'

else

render
action:
"edit"

end

end

def
destroy

@todo
=

@todo.destroy

redirect_to
todos_path,
notice:
'Todo
was
successfully
destroyed.'

end
end


hey! there is
duplicate* code
now

is there? or did we
just move it
around?

Todo became ApiLib::Todo


we now have a
reference
implementation

make sure
to cache!!

The Hack

Please don’t
do this!


I’m Serious.

Don’t use
this hack!


I probably shouldn’t
even show you it.


Ok, I’ll show you,
but don’t tell
people where you
heard it.

class
TodosController
<

def
index

res
=
Api::V1::TodosController.action(:index).call(env)

@todos
=
JSON.parse(res[2].body).map
do
|data|

OpenStruct.new(data)

end

end

end


projects
worth noting

rails-api

api_doc

Final Thoughts


Final Thoughts

• Consume your API


Final Thoughts


• Version your API


Final Thoughts



• Document your API


Final Thoughts



• Document your API

• Did I mention consume your own API?


Thank You
http://www.metacasts.tv
CONFOO2013
@markbates

Building an API in Rails without Realizing It

More Related Content

Similar to Building an API in Rails without Realizing It

More from Mark

Recently uploaded

Building an API in Rails without Realizing It