Building Better Web APIs with Rails

Presented at Ancient City Ruby 2015

Transcript

1. BUILDINg BETTER WITH railS web APIS @caike Carlos Souza Code School
4. codeschool.com
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 five things
11. endpoints, resources and url-to-controller mappings ROUTES
12. URLs are very important /projects /projects/archived /projects/:id/archive
13. resources :projects GET
 POST
 PATCH (PUT) 
 DELETE ... Projects#index Projects#create Projects#show Projects#update Projects#destroy ... paths methods actions /projects /projects/:id
14. resources :projects paths /projects/archived
 /projects/:id/archive
 /projects /projects/:id ?????
15. resources :projects end end end member do post 'archive' 
 collection do get 'archived' do
16. 
 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'
17. 
 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'
18. 
 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'
19. conneg content negotiation
20. 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.
21. 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
22. class ProjectSerializer < ActiveModel::Serializer attributes :id, :title, :amount embed :ids, include: true has_many :products end https://github.com/rails-api/active_model_serializers ActiveModel::Serializers
23. class ProjectSerializer < ActiveModel::Serializer attributes :id, :title, :amount embed :ids, include: true has_many :products end https://github.com/rails-api/active_model_serializers ActiveModel::Serializers defaults to JSON-API
24. JSON-API A standard for building APIs in JSON. "it's your anti-bikeshedding weapon"
25. 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
27. 創建資源
28. تسا هدش داجیا عبانم
29. Resource è stato creato
30. 創建資源 تسا هدش داجیا عبانم Resource è stato creato
31. 201request fulfilled and new resource created
32. A Status Code is worth a thousand words Author Unknown
33. module API class ReportsController < ApplicationController def create head 200 end end end A time-consuming request... takes ~20 seconds Report.generate
34. class ReportJob < ActiveJob::Base queue_as :default def perform(*args) end end ActiveJob Report.generate
35. module API class ReportsController < ApplicationController def create head 200 end end end Creating the job ReportJob.perform_later
36. module API class ReportsController < ApplicationController def create ReportJob.perform_later head 200 end end end Creating the job
37. module API class ReportsController < ApplicationController def create ReportJob.perform_later head 202 end end end 202 accepted for processing, but processing has not been completed.
38. AUTHentication preventing unauthorized access to protected resources
39. • 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
40. token for the Backpack API providing the token Typically available out-of-band on a user settings page
41. 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
42. UUID - Universally Unique Identifier GENERATING TOKENS RFC 4122
43. 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
44. end def generate_auth_token .gsub(/\-/,'') end omits the hyphens SecureRandom.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
45. $ 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 WITH curl
46. versioning resources Version
47. MAJOR
 incompatible changes 
 MINOR
 backwards-compatible changes 
 PATCH
 backwards-compatible bug fixes http://semver.org/ Semantic versioning Works great for software libraries
48. 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
50. 410 The requested resource is no longer available 
 at the server and no forwarding address 
 is known.
51. 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”
52. TESTS automated verification
53. API Unit Tests testing apis Not the time nor place to test business logic
54. API • Status Code • Mime Types • Authentication WHAT SHOULD WE TEST ?
55. API HOW SHOULD WE TEST ? Requesting endpoints and verifying responses $ rails g integration_test <doing-something>
56. 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
57. 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
58. 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
59. 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
60. 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
61. 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
62. http://railsapis.codeschool.com/
63. ruby5.codeschool.com
64. carlos@codeschool.com Want to Podcast ? Get in touch! fivejs.codeschool.com iosbytes.codeschool.com
65. BUILDINg BETTER WITH railS web APIS @caike Carlos Souza Code School Thank You! https://www.flickr.com/photos/glimeend/5387716362