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.

Transcript

1. Building Web APIs Pragmatic Approach (with Rails) Wednesday, October 23, 13
2. 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
3. Why Web APIs? Wednesday, October 23, 13
4. Multiple Clients/ Consumers Wednesday, October 23, 13
5. Desktop (Native and Browser) Mobile Devices Smart TVs Smart Watches Whatever’s Next Wednesday, October 23, 13
6. Service Oriented Architecture Wednesday, October 23, 13
7. 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
8. Rise of Client- Side MVC Frameworks Wednesday, October 23, 13
9. Ember.JS (emberjs.com) AngularJS (angularjs.org) Backbone.JS (backbonejs.org) The Big Three Wednesday, October 23, 13
10. Caveats to Web APIs Wednesday, October 23, 13
11. 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
12. Using Rails For Web APIs Wednesday, October 23, 13
13. Pros Wednesday, October 23, 13
14. Familiar DSL Makes it easy to leverage existing controllers with a few tweaks Wednesday, October 23, 13
15. Cons Wednesday, October 23, 13
16. Originally built and intended for browser applications where it (Rails) handles the view Lots of middleware meant for browser apps Wednesday, October 23, 13
17. Alternatives? Wednesday, October 23, 13
18. Several Frameworks Grape Rocket Pants Rails-API Sinatra (not purely for APIs) Utilities Rabl JBuilder Active Model Serializers Wednesday, October 23, 13
19. See The Ruby Toolbox’s “API Builders” category for more. Wednesday, October 23, 13
20. We’ll use Rails-API in our examples. Wednesday, October 23, 13
21. “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
22. $ 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
23. $ 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
24. $ 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
25. See Rails Guides (Chapter 3) for info on Rails’ Internal Middleware stack Wednesday, October 23, 13
26. REST + JSON vs SOAP Wednesday, October 23, 13
27. Testing Wednesday, October 23, 13
28. What to Test HTTP Status Codes Response Bodies Wednesday, October 23, 13
29. 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
30. Detour... Wednesday, October 23, 13
31. 418 - I’m a teapot http://tools.ietf.org/html/rfc2324 Wednesday, October 23, 13
32. Wednesday, October 23, 13
33. ...and we’re back Wednesday, October 23, 13
34. 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
35. 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
36. How to Test What about unit tests for your models and functional tests for your controllers? Sure. Be pragmatic. Wednesday, October 23, 13
37. Integration Testing Use Rack::Test to test HTTP requests on URLs Use RSpec Request Specs Wednesday, October 23, 13
38. Versioning Wednesday, October 23, 13
39. Versioning API frameworks (Grape, Rocket Pants) usually have versioning capabilities built-in Gems: versionist, api-versions, etc Wednesday, October 23, 13
40. 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
41. We’ll roll our own (header-based versioning) in our examples Wednesday, October 23, 13
42. Authentication Wednesday, October 23, 13
43. Authentication HTTP Basic Authentication (i.e. http_basic_authenticate in a base controller) Wednesday, October 23, 13
44. Authentication Token-based (i.e. token in params or in an ‘Authorization’ header) Wednesday, October 23, 13
45. Authentication OAuth (if apps login on behalf of your users, think FB, Twitter, etc) Wednesday, October 23, 13
46. Use SSL in Production Wednesday, October 23, 13
47. We’ll use token-based authentication in our examples Wednesday, October 23, 13
48. Let’s take a break Wednesday, October 23, 13
49. Let’s build an API Wednesday, October 23, 13
50. 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
51. Follow along: https://github.com/jboursiquot/ web-apis-with-rails-talk Wednesday, October 23, 13
52. You did it! Wednesday, October 23, 13
53. Wait! I’ve got changes for v2. Wednesday, October 23, 13
54. wat Wednesday, October 23, 13
55. 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
56. Follow along: https://github.com/jboursiquot/ web-apis-with-rails-talk Wednesday, October 23, 13
57. Recap Wednesday, October 23, 13
58. 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
59. @jboursiquot Thanks! Got Questions? Wednesday, October 23, 13