Presented at Confoo (Montreal, Canada) on 3/1/2013 In this talk I’ll show you how to build your application and get a working, well tested, and useable API in the process, with almost no extra overhead. I’ll also show you how to do it without making your controllers a mess of respond_to blocks. If anything, you’re controllers will become cleaner and leaner.

1. Rails APIs
Monday, February 25, 13

2. @markbates
Monday, February 25, 13

3. Monday, February 25, 13

4. Monday, February 25, 13

5. http://www.metacasts.tv
CONFOO2013
Monday, February 25, 13

6. Rails APIs
Monday, February 25, 13

7. Rails APIs
Monday, February 25, 13

8. e b APIs
Rails
W
Monday, February 25, 13

9. you’re probably
doing it wrong
Monday, February 25, 13

10. Don’t Panic!
Monday, February 25, 13

11. most APIs are an
after thought
Monday, February 25, 13

12. we can prevent
that!
Monday, February 25, 13

13. 3 simple rules for
building an API
Monday, February 25, 13

14. 1. consume your
own API
Monday, February 25, 13

15. 2. document your
API
Monday, February 25, 13

16. 3. version your
API
Monday, February 25, 13

17. building the API
Monday, February 25, 13

18. SOA
Monday, February 25, 13

19. Service Oriented
Architecture
Monday, February 25, 13

20. SOA Pros
Monday, February 25, 13

21. SOA Pros
• Scales Easily
Monday, February 25, 13

22. SOA Pros
• Scales Easily
• Separate Concerns/Very Clean
Monday, February 25, 13

23. SOA Pros
• Scales Easily
• Separate Concerns/Very Clean
• Can be easier to maintain
Monday, February 25, 13

24. SOA Pros
• Scales Easily
• Separate Concerns/Very Clean
• Can be easier to maintain
• Solid Architecture
Monday, February 25, 13

25. SOA Pros
• Scales Easily
• Separate Concerns/Very Clean
• Can be easier to maintain
• Solid Architecture
• Easier to refactor/rebuild
Monday, February 25, 13

26. SOA Cons
Monday, February 25, 13

27. SOA Cons
• Can be more difficult to maintain
Monday, February 25, 13

28. SOA Cons
• Can be more difficult to maintain
• More complex deploys
Monday, February 25, 13

29. SOA Cons
• Can be more difficult to maintain
• More complex deploys
• Managing several applications
Monday, February 25, 13

30. SOA Cons
• Can be more difficult to maintain
• More complex deploys
• Managing several applications
• Potential for ‘out-of-sync’ apps
Monday, February 25, 13

31. SOA Cons
• Can be more difficult to maintain
• More complex deploys
• Managing several applications
• Potential for ‘out-of-sync’ apps
• More difficult to test integration
Monday, February 25, 13

32. API Client
Monday, February 25, 13

33. Client
API
Client
Monday, February 25, 13

34. Client
API Client
Client
Monday, February 25, 13

35. Client
Service 1
Service 2 Client
Service 3
Client
Monday, February 25, 13

36. a quick detour
Monday, February 25, 13

37. Rails encourages
poor API design!
Monday, February 25, 13

38. Monday, February 25, 13

39.
#
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
=
Todo.find(params[:id])
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:
:unprocessable_entity
}
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.find(params[:id])
@todo.destroy
#
GET
/todos/1/edit
def
edit
respond_to
do
|format|
@todo
=
Todo.find(params[:id])
format.html
{
redirect_to
todos_url
}
end
format.json
{
head
:no_content
}
end
end
end
Monday, February 25, 13

40. Don’t Scaffold!
Monday, February 25, 13

41. Monday, February 25, 13

42. class
TodosController
<
ApplicationController
def
index
@todos
=
Todo.all
end
def
show
@todo
=
Todo.find(params[:id])
end
def
new
@todo
=
Todo.new
end
def
edit
@todo
=
Todo.find(params[:id])
end
def
create
@todo
=
Todo.new(params[:todo])
if
@todo.save
redirect_to
@todo,
notice:
'Todo
was
successfully
created.'
else
render
action:
"new"
end
end
def
update
@todo
=
Todo.find(params[:id])
if
@todo.update_attributes(params[:todo])
redirect_to
@todo,
notice:
'Todo
was
successfully
updated.'
else
render
action:
"edit"
end
end
def
destroy
@todo
=
Todo.find(params[:id])
@todo.destroy
redirect_to
todos_path,
notice:
'Todo
was
successfully
destroyed.'
end
end
Monday, February 25, 13

43. class
TodosController
<
ApplicationController
inherit_resources
end
Monday, February 25, 13

44. Inherited Resources
https://github.com/josevalim/inherited_resources
Monday, February 25, 13

45. Monday, February 25, 13

46. class
Api::V1::TodosController
<
ApplicationController
respond_to
:json
before_filter
do
request.format
=
:json
end
def
index
@todos
=
Todo.all
respond_with
@todos
end
def
show
@todo
=
Todo.find(params[:id])
respond_with
@todo
end
def
create
@todo
=
Todo.new(params[:todo])
if
@todo.save
respond_with
@todo
else
render
json:
@todo.errors,
status:
:unprocessable_entity
end
end
def
update
@todo
=
Todo.find(params[:id])
if
@todo.update_attributes(params[:todo])
respond_with
@todo
else
render
json:
@todo.errors,
status:
:unprocessable_entity
end
end
def
destroy
@todo
=
Todo.find(params[:id])
@todo.destroy
head
:no_content
end
end
Monday, February 25, 13

47. version your API!
Api::V1::TodosController
/api/v1/todos
Monday, February 25, 13

48. i prefer URL
versioning
Monday, February 25, 13

49. others prefer
header versioning
Monday, February 25, 13

50. just pick one and
stick with it!
Monday, February 25, 13

51. SOA Review
Monday, February 25, 13

52. SOA Review
• We’ve cleaned up our code
Monday, February 25, 13

53. SOA Review
• We’ve cleaned up our code
• We know the API Works
Monday, February 25, 13

54. SOA Review
• We’ve cleaned up our code
• We know the API Works
• We’re now in a good place to scale
Monday, February 25, 13

55. consuming the API
Monday, February 25, 13

56. don’t use
Rails views
Monday, February 25, 13

57. JavaScript
Monday, February 25, 13

58. CORS
Monday, February 25, 13

59. Cross-origin
Resource Sharing
Monday, February 25, 13

60. rack-cors
https://github.com/cyu/rack-cors
Monday, February 25, 13

61. 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
Monday, February 25, 13

62. JavaScript Pros
Monday, February 25, 13

63. JavaScript Pros
• Scales Easily/Pushes processing to client side
Monday, February 25, 13

64. JavaScript Pros
• Scales Easily/Pushes processing to client side
• Separate Concerns/Very Clean
Monday, February 25, 13

65. JavaScript Pros
• Scales Easily/Pushes processing to client side
• Separate Concerns/Very Clean
• Can be easier to maintain
Monday, February 25, 13

66. JavaScript Pros
• Scales Easily/Pushes processing to client side
• Separate Concerns/Very Clean
• Can be easier to maintain
• “Responsive/Native” feel for clients
Monday, February 25, 13

67. JavaScript Pros
• Scales Easily/Pushes processing to client side
• Separate Concerns/Very Clean
• Can be easier to maintain
• “Responsive/Native” feel for clients
• Easily consumes your API
Monday, February 25, 13

68. JavaScript Cons
Monday, February 25, 13

69. JavaScript Cons
• Can be more difficult to maintain
Monday, February 25, 13

70. JavaScript Cons
• Can be more difficult to maintain
• Multiple languages (backend/front-end)
Monday, February 25, 13

71. JavaScript Cons
• Can be more difficult to maintain
• Multiple languages (backend/front-end)
• Difficult to test integration
Monday, February 25, 13

72. JavaScript Cons
• Can be more difficult to maintain
• Multiple languages (backend/front-end)
• Difficult to test integration
• JavaScript
Monday, February 25, 13

73. JavaScript Cons
• Can be more difficult to maintain
• Multiple languages (backend/front-end)
• Difficult to test integration
• JavaScript
• Paradigm shift in architecture
Monday, February 25, 13

74. JavaScript Cons
• Can be more difficult to maintain • Accessibility issues
• Multiple languages (backend/front-end)
• Difficult to test integration
• JavaScript
• Paradigm shift in architecture
Monday, February 25, 13

75. JavaScript Cons
• Can be more difficult to maintain • Accessibility issues
• Multiple languages (backend/front-end) • SEO concerns
• Difficult to test integration
• JavaScript
• Paradigm shift in architecture
Monday, February 25, 13

76. JavaScript Cons
• Can be more difficult to maintain • Accessibility issues
• Multiple languages (backend/front-end) • SEO concerns
• Difficult to test integration • !!Internet Explorer!!
• JavaScript
• Paradigm shift in architecture
Monday, February 25, 13

77. pick a
framework
Monday, February 25, 13

78. don’t just
use jQuery
Monday, February 25, 13

79. the big
three
Monday, February 25, 13

80. Backbone.js
http://backbonejs.org/
Monday, February 25, 13

81. ember
http://emberjs.com/
Monday, February 25, 13

82. Angular.js
http://angularjs.org/
Monday, February 25, 13

83. i can’t use
JavaScript
Monday, February 25, 13

84. 2 approaches
Monday, February 25, 13

85. “compiled” sites
Monday, February 25, 13

86. build your own
API library (and
open source it!)
Monday, February 25, 13

87. Monday, February 25, 13

88. class
TodosController
<
ApplicationController
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
=
ApiLib::Todo.find(params[:id])
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
=
ApiLib::Todo.find(params[:id])
if
@todo.update_attributes(params[:todo])
redirect_to
@todo,
notice:
'Todo
was
successfully
updated.'
else
render
action:
"edit"
end
end
def
destroy
@todo
=
ApiLib::Todo.find(params[:id])
@todo.destroy
redirect_to
todos_path,
notice:
'Todo
was
successfully
destroyed.'
end
end
Monday, February 25, 13

89. hey! there is
duplicate* code
now
Monday, February 25, 13

90. is there? or did we
just move it
around?
Monday, February 25, 13

91. Todo became ApiLib::Todo
Monday, February 25, 13

92. we now have a
reference
implementation
Monday, February 25, 13

93. make sure
to cache!!
Monday, February 25, 13

94. The Hack
Monday, February 25, 13

95. Please don’t
do this!
Monday, February 25, 13

96. I’m Serious.
Monday, February 25, 13

97. Don’t use
this hack!
Monday, February 25, 13

98. I probably shouldn’t
even show you it.
Monday, February 25, 13

99. Ok, I’ll show you,
but don’t tell
people where you
heard it.
Monday, February 25, 13

100. Monday, February 25, 13

101. class
TodosController
<
ApplicationController
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
Monday, February 25, 13

102. projects
worth noting
Monday, February 25, 13

103. rails-api
Monday, February 25, 13

104. Monday, February 25, 13

105. api_doc
Monday, February 25, 13

106. Monday, February 25, 13

107. Monday, February 25, 13

108. Final Thoughts
Monday, February 25, 13

109. Final Thoughts
• Consume your API
Monday, February 25, 13

110. Final Thoughts
• Consume your API
• Version your API
Monday, February 25, 13

111. Final Thoughts
• Consume your API
• Version your API
• Document your API
Monday, February 25, 13

112. Final Thoughts
• Consume your API
• Version your API
• Document your API
• Did I mention consume your own API?
Monday, February 25, 13

113. Thank You
http://www.metacasts.tv
CONFOO2013
@markbates
Monday, February 25, 13