Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Building Web APIs with Rails

Building Web APIs with Rails

This talk was given to the Fall 2013 cohort of Launch Academy. The talk explains the difference between traditional web applications in the context of Rails and data-only applications that expose their functionality through REST+JSON interfaces.

Johnny Boursiquot

September 20, 2013
Tweet

More Decks by Johnny Boursiquot

Other Decks in Technology

Transcript

  1. What we’ll cover Why Web APIs? Using Rails for Web

    APIs Testing, versioning, authentication and documentation Implement an API Next steps Wednesday, October 23, 13
  2. Desktop (Native and Browser) Mobile Devices Smart TVs Smart Watches

    Whatever’s Next Wednesday, October 23, 13
  3. More focused and re-usable services Easier data exchange across disparate

    systems Easier to maintain in most cases Easier to scale in most cases Wednesday, October 23, 13
  4. Multiple apps to deploy, monitor and maintain Integration testing can

    be more difficult (clients and APIs tend to be tested in isolation) Clients risk falling out of date as API updates are released (requiring a non- breaking, backwards-compatible versioning strategy) Wednesday, October 23, 13
  5. Originally built and intended for browser applications where it (Rails)

    handles the view Lots of middleware meant for browser apps Wednesday, October 23, 13
  6. Several Frameworks Grape Rocket Pants Rails-API Sinatra (not purely for

    APIs) Utilities Rabl JBuilder Active Model Serializers Wednesday, October 23, 13
  7. “rails-api is a plugin [which] modifies Rails applications, trimming down

    usually unneeded Rails functionalities for API applications.” http://blog.wyeworks.com/2012/4/20/rails-for-api-applications-rails-api-released/ Wednesday, October 23, 13
  8. $ rake middleware use ActionDispatch::Static use Rack::Lock use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware: 0x007fcf0b2181f8>

    use Rack::Runtime use Rack::MethodOverride use ActionDispatch::RequestId use Rails::Rack::Logger use ActionDispatch::ShowExceptions use ActionDispatch::DebugExceptions use ActionDispatch::RemoteIp use ActionDispatch::Reloader use ActionDispatch::Callbacks use ActiveRecord::Migration::CheckPending use ActiveRecord::ConnectionAdapters::ConnectionManagement use ActiveRecord::QueryCache use ActionDispatch::Cookies use ActionDispatch::Session::CookieStore use ActionDispatch::Flash use ActionDispatch::ParamsParser use Rack::Head use Rack::ConditionalGet use Rack::ETag use MetaRequest::Middlewares::MetaRequestHandler use MetaRequest::Middlewares::Headers use MetaRequest::Middlewares::AppRequestHandler rails middleware stack Wednesday, October 23, 13
  9. $ rake middleware use ActionDispatch::Static use Rack::Lock use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware: 0x007fca3cd06048>

    use Rack::Runtime use ActionDispatch::RequestId use Rails::Rack::Logger use ActionDispatch::ShowExceptions use ActionDispatch::DebugExceptions use ActionDispatch::RemoteIp use ActionDispatch::Reloader use ActionDispatch::Callbacks use ActiveRecord::Migration::CheckPending use ActiveRecord::ConnectionAdapters::ConnectionManagement use ActiveRecord::QueryCache use ActionDispatch::ParamsParser use Rack::Head use Rack::ConditionalGet use Rack::ETag rails-api middleware stack Wednesday, October 23, 13
  10. $ rake middleware use ActionDispatch::Static use Rack::Lock use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware: 0x007fcf0b2181f8>

    use Rack::Runtime use Rack::MethodOverride use ActionDispatch::RequestId use Rails::Rack::Logger use ActionDispatch::ShowExceptions use ActionDispatch::DebugExceptions use ActionDispatch::RemoteIp use ActionDispatch::Reloader use ActionDispatch::Callbacks use ActiveRecord::Migration::CheckPending use ActiveRecord::ConnectionAdapters::ConnectionManagement use ActiveRecord::QueryCache use ActionDispatch::Cookies use ActionDispatch::Session::CookieStore use ActionDispatch::Flash use ActionDispatch::ParamsParser use Rack::Head use Rack::ConditionalGet use Rack::ETag use MetaRequest::Middlewares::MetaRequestHandler use MetaRequest::Middlewares::Headers use MetaRequest::Middlewares::AppRequestHandler rails-api vs rails middleware Wednesday, October 23, 13
  11. See Rails Guides (Chapter 3) for info on Rails’ Internal

    Middleware stack Wednesday, October 23, 13
  12. HTTP Status Codes 2xx - Success (e.g. 200 Ok, 201

    Created, etc) 4xx - Client error (e.g. 401 Unauthorized, 403 Forbidden, 404 Not Found, etc) 5xx - Server Error (something went wrong on the server side, not uncommon) Great resource: http://httpstatus.es/ Wednesday, October 23, 13
  13. Response Bodies Verify response bodies contain the information you request

    of the API Verify that desired processing or business logic takes place and is represented in the response Wednesday, October 23, 13
  14. How to Test Integration Testing Tests for expected behavior of

    your API Similar to what we do with Capybara when testing user behavior Do not use Capybara, however Wednesday, October 23, 13
  15. How to Test What about unit tests for your models

    and functional tests for your controllers? Sure. Be pragmatic. Wednesday, October 23, 13
  16. Integration Testing Use Rack::Test to test HTTP requests on URLs

    Use RSpec Request Specs Wednesday, October 23, 13
  17. Versioning API frameworks (Grape, Rocket Pants) usually have versioning capabilities

    built-in Gems: versionist, api-versions, etc Wednesday, October 23, 13
  18. Versioning Roll your own: Versioning by URL (e.g. http://domain/api/v1/contacts) Versioning

    with Accept header (e.g. curl -H 'Accept: application/ vnd.contax.v1' http://domain/api/ contacts) Wednesday, October 23, 13
  19. Authentication OAuth (if apps login on behalf of your users,

    think FB, Twitter, etc) Wednesday, October 23, 13
  20. Requirements Build a contact management API where users can store

    and retrieve their contacts. Contacts have a name and email. API must be versioned, secured, tested and documented. Wednesday, October 23, 13
  21. Version 2 Requirements Contacts need name broken up into first,

    last Add support for twitter usernames Don’t break the API - existing clients depend on it Wednesday, October 23, 13
  22. SOA is your friend REST + JSON Use Rails-API. It’s

    Rails, just lighter. Integration Testing Use Rack::Test, RSpec Request Specs Test HTTP status codes and response bodies Version your API Secure your API Document your API Wednesday, October 23, 13