Building Better Web APIs with Rails
3 likes1,379 views
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
Building Better Web APIs with Rails
- 1. BUILDINg BETTER WITH railS Devils Tower, WY web APIS @caikeCarlos Souza Code School
- 3. tryruby.org
- 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
- 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
- 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”
- 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
- 58. Thank you BUILDINg BETTER WITH railS@caikeCarlos Souza Code School web APIS Devils Tower, WY