This document discusses various techniques for building APIs with Rails including: - Using Rails routing and controllers to define API endpoints and resources - Content negotiation to support different response formats like JSON and XML - Authentication methods like HTTP basic authentication and token-based authentication - Versioning API resources to maintain backwards compatibility - Testing APIs to validate status codes, response formats, authentication, and more

1. BUILDINg BETTER
WITH railS
Devils Tower, WY
web APIS
@caikeCarlos Souza
Code School

2. codeschool.com

3. tryruby.org

4. railsforzombies.org

6. perfect
rails web app
Deadline
Budget
Features
Tests

7. “We need a snappier
experience”

8. “We’ve detected the majority
of our visitors come from
mobile devices.
We need to launch a native app
as soon as possible!”

9. “Does our web app
expose an API ?”

10. • Routes
• CONNEG
• AUTH
• VERSION
• Tests

11. endpoints, resources and
url-to-controller mappings
ROUTES

12. URLs are very important
/gists
/gists/public
/gists/starred

14. resources :projects
GET
POST
PATCH (PUT)
DELETE
!
!
...
Projects#index
Projects#create
Projects#show
Projects#update
Projects#destroy
...
paths methods actions
/projects
/projects/:id

15. resources :projects
paths
/projects/archived
/projects/:id/archive
/projects
/projects/:id
?????

16. resources :projects
end
end
end
member do
post 'archive'
collection do
get 'archived'
do

17.
!
get 'active'
get 'suspended'
!
!
!
post 'activate'
post 'suspend'
!
!
resources :projects
end
end
end
do
member do
post 'archive'
collection do
get 'archived'
post 'create_review'

18.
!
get 'active'
get 'suspended'
!
!
!
post 'activate'
post 'suspend'
!
!
resources :projects
end
end
end
do
member do
post 'archive'
collection do
get 'archived', to: 'archived_projects#index'
, to: 'active_projects#index'
, to: 'suspended_projects#index'
, to: 'archived_projects#create'
, to: 'active_projects#create'
, to: 'suspended_projects#create'
post 'create_review'

19.
!
get 'active'
get 'suspended'
!
!
!
post 'activate'
post 'suspend'
!
!
resources :projects
end
end
end
do
member do
post 'archive'
collection do
get 'archived'
resources :reviews, only: :create
, to: 'archived_projects#index'
, to: 'active_projects#index'
, to: 'suspended_projects#index'
, to: 'archived_projects#create'
, to: 'active_projects#create'
, to: 'suspended_projects#create'

20. app/controllers/api/projects_controller.rb
module Api
class ProjectsController < ApplicationController
def index
...
end
end
end

21. ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym 'API'
end
config/initializers/inflections.rb
module API
class ProjectsController < ApplicationController
def index
...
end
end
end

22. connegcontent negotiation

23. Client A
API
I’m a Rich Java$cript Application
and I want JSON!
Hey, I’m an Enterprise Java Application
and I want XML! (Ha Ha, Business!)
¯_(ツ)_/¯
Oi, soy un browser e quiero HTML!
response in JSON
respuesta en HTML
response in XML
Client B
Client C
content negotiation
The process in which client and server
determine the best representation for a response
when many are available.

24. /projects.json
GET /projects
Accept: application/json
vs.
Rails nicety
Part of the HTTP spec
client requests

25. responders
extracted out to
responders gem
in Rails 4.2
module API
class ProjectsController < ApplicationController
respond_to :json, :xml
!
def index
@projects = Project.all
!
respond_with(@projects)
end
end
end

26. calls #to_json
calls #to_xml
respond_to
module API
class ProjectsController < ApplicationController
def index
@projects = Project.recent
!
respond_to do |format|
format.json { render json: @projects, status: 200 }
format.xml { render xml: @projects, status: 200 }
end
end
end
end

27. JBuilder
json.content format_content(@message.content)
json.(@message, :created_at, :updated_at)
!
json.author do
json.name @message.creator.name.familiar
json.url url_for(@message.creator, format: :json)
end
https://github.com/rails/jbuilder

28. class ProjectSerializer < ActiveModel::Serializer
attributes :id, :title, :amount
!
embed :ids, include: true
has_many :products
end
defaults to JSON-API
https://github.com/rails-api/active_model_serializers
ActiveModel::Serializers

29. module SongsRepresenter
include Roar::JSON::JsonApi
name :songs
!
property :id
property :title
end
class SongRepresenter < Roar::Decorator
include Roar::JSON::JsonApi
name :songs
!
property :id
property :title
end
https://github.com/apotonick/roar
using Mixins using Decorators
Roar

30. AUTHenticationpreventing unauthorized access
to protected resources

31. • Quick and Simple
• Reutilizes existing credentials
• HTTP spec (RFC 2617)
http basic AUTH

32. http basic AUTH
module API
class ProjectsController < ApplicationController
before_action :authenticate_or_request
!
protected
!
def authenticate_or_request
authenticate_or_request_with_http_basic do |user, pwd|
User.authenticate(user, pwd)
end
end
end
end

33. use the -u option
$ curl -I http://carlos:secret@localhost:3000/projects
!
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
$ curl -Iu 'carlos:secret' http://localhost:3000/projects
!
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
http basic AUTH with curl

34. • Can easily expire or regenerate tokens.
• Any vulnerability is limited to API access.
• Multiple tokens for each user.
• Different access rules can be implemented.
API
Projects
Forum
Admin
Client A
token based auth

35. token for the Backpack API
providing the token
Typically available out-of-band
on a user settings page

36. token for the Digital Ocean API
For security purposes,
some services will only display
the access token once.
providing the token

37. token based auth
module API
class ProjectsController < ApplicationController
before_action :authenticate_or_request
!
protected
!
def authenticate_or_request
authenticate_or_request_with_http_token do |token, opt|
User.find_by(auth_token: token)
end
end
end
end

38. UUID - Universally Unique Identifier
GENERATING TOKENS
RFC 4122

39. We can use the Ruby standard library
SecureRandom.uuid
f4ea855f-d303-43e6-bee3-94581c0ecb21
90ab3255-ce33-4022-8349-b7979655b07c
371c760d-2539-41b9-b665-98c255d4c323
...
GENERATING TOKENS

40. end
def generate_auth_token
.gsub(/-/,'')
end
omits the hyphensSecureRandom.uuid
class User < ActiveRecord::Base
before_create :set_auth_token
!
private
!
def set_auth_token
return if auth_token.present?
self.auth_token = generate_auth_token
end
!
a47a8e54b11c4de5a4a351734c80a14a
9fa8a147b10c4efca3e8592b3a1c2729
823c1c984d504f66a2e6cbb2eb69e842
...
GENERATING TOKENS

41. $ curl -IH "Authorization: Token token=16d7d6089b8fe0c5e19bfe10bb156832"
http://localhost:3000/episodes
!
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
use the -H option
token based auth com curl

42. versioning resources
Version

43. MAJOR
incompatible changes
MINOR
backwards-compatible changes
PATCH
backwards-compatible bug fixes
http://semver.org/Semantic versioning
Works great for software libraries

44. V1/V1
feature X, feature Y
/V2
feature X, feature Y,
feature Z
Compatible changes:
• addition of a new format (i.e. JSON, XML )
• addition of a new property on a resource
• renaming of an end-point (use 3xx status code!)
• Only use major version.
• Changes cannot break existing clients.
• No need to bump version on compatible changes.
versioning services

45. 410 Gone

46. https://www.mnot.net/blog/2012/12/04/api-evolution
“The biggest way to avoid new
major versions is to make as many
of your changes backwards-compatible
as possible”

47. TESTSautomated verification

48. API
Unit Tests
testing apis
Not the time nor place to test business logic

49. API
• Status Code
• Mime Types
• Authentication
WHAT SHOULD WE TEST ?

50. API
HOW SHOULD WE TEST ?
Requesting endpoints and verifying responses
$ rails g integration_test <doing-something>

51. testing status code
require 'test_helper'
!
class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { host! 'api.example.com' }
!
test 'returns list of projects' do
get '/projects'
assert_equal 200, response.status
refute_empty response.body
end
end

52. testing status code
require 'test_helper'
!
class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { host! 'api.example.com' }
!
test 'returns list of projects' do
get '/projects'
assert_equal 200, response.status
refute_empty response.body
end
end

53. testing mime types
class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { host! 'api.example.com' }
test 'returns projects in JSON' do
get '/projects', {}, { 'Accept' => Mime::JSON }
assert_equal Mime::JSON, response.content_type
end
test 'returns projects in XML' do
get '/projects', {}, { 'Accept' => Mime::XML }
assert_equal Mime::XML, response.content_type
end
end

54. testing mime types
class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { host! 'api.example.com' }
test 'returns projects in JSON' do
get '/projects', {}, { 'Accept' => Mime::JSON }
assert_equal Mime::JSON, response.content_type
end
test 'returns projects in XML' do
get '/projects', {}, { 'Accept' => Mime::XML }
assert_equal Mime::XML, response.content_type
end
end

55. class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { @user = User.create! }
setup { host! 'api.example.com' }
!
test 'valid authentication with token' do
get '/projects', {}, { 'Authorization' => "Token token=#{@user.auth_token}"}
assert_equal 200, response.status
assert_equal Mime::JSON, response.content_type
end
!
test 'invalid authentication' do
get '/projects', {}, { 'Authorization' => "Token token=#{@user.auth_token}fake" }
assert_equal 401, response.status
end
end
testing access rules

56. class ListingProjectsTest < ActionDispatch::IntegrationTest
setup { @user = User.create! }
setup { host! 'api.example.com' }
!
test 'valid authentication with token' do
get '/projects', {}, { 'Authorization' => "Token token=#{@user.auth_token}"}
assert_equal 200, response.status
assert_equal Mime::JSON, response.content_type
end
!
test 'invalid authentication' do
get '/projects', {}, { 'Authorization' => "Token token=#{@user.auth_token}fake" }
assert_equal 401, response.status
end
end
testing access rules

57. railsapis.codeschool.com

58. Thank you
BUILDINg BETTER
WITH railS@caikeCarlos Souza
Code School
web APIS
Devils Tower, WY