API Safari

A survey on how to create an API using different libraries

The objective is to show that Ruby has a rich ecosystem for building API servers pick one that you like

Would be covering Grape and Webmachine for REST APIs and Celluloid for RPC Apis

Grape is like Sinatra but focussed on creating a REST API

Webmachine is a port of an Erlang library which treats the HTTP request-respose cycle as a state machine

Not covering rails-api as it is like Rails

Celluloid is a framework for building multithreaded programs Will be using it to build a RPC server

Transcript

1. API SAFARI Explore choices for building an API by @deepak_kannan http://codemancers.com/ 1
2. RUBY IS FUN 2
3. RUBY IS PRODUCTIVE 3
4. RUBY HAS AWESOME CHOICES 4
5. PICK A LIB. AND HAVE FUN 5
6. FRAMEWORKS Which we will look at 6
7. WEBMACHINE https://github.com/seancribbs/webmachine-ruby 7
8. GRAPE https://github.com/intridea/grape 8
9. CELLULOID FOR RPC https://github.com/celluloid/ 9
10. WHAT R U USING ? poll 10
11. GOOD API mostly well understood 11
12. USE HTTP VERBS 12
13. MEANINGFUL URLS Different urls. Not a single url with many attributes 13
14. STARBUCKS EXAMPLE http://www.infoq.com/articles/webber-rest-workflow 14
15. POST /ORDER HTTP 201 Created in Response 15
16. PUT /ORDERS?ID=1 HTTP 200 OK or 409 conflict in Response 16
17. PUT /PAYMENT HTTP 201 Created in Response 17
18. GET /ORDERS?STATUS=PAID HTTP 200 in Response 18
19. HYPERMEDIA Talk is not Hypermedia specific 19
20. GITHUB: /DEEPAK/API_SAFARI 20
21. GRAPE https://github.com/intridea/grape 21
22. Y U NOT USE RAILS ? 22
23. RAILS IS GOOD 23
24. 1 # config/routes.rb 2 resources :orders 3 4 # app/controllers/orders_controller.rb 5 class OrdersController < ApplicationController 6 respond_to :json 7 8 def index 9 end 10 11 def show 12 end 13 end 14 15 24
25. RAILS IS COMFORTABLE 25
26. USE RAILS API https://github.com/rails-api/rails-api 26
27. GRAPE 27
28. POWER CORRUPTS ? 28
29. 1 class ApiConstraints 2 def matches?(req) 3 # match req.headers['Accept'] 4 end 5 end 6 7 namespace :api do 8 scope(module: :v2, 9 constraints: ApiConstraints.new('...')) do 10 resources :products 11 end 12 end 13 14 RAILS IS POWERFUL 29
30. DSL Less Lines of Code 1 module Starbucks 2 class API < Grape::API 3 version 'v2' , using: :header 4 end 5 end 30
31. EASE OF DEVELOPMENT 31
32. LIKE SINATRA BUT ONLY FOR API 32
33. DSL SUGAR 33
34. SPECIFY URL PREFIX 1 module Starbucks 2 class API < Grape::API 3 prefix 'starbucks' 4 version 'v2' 6 format :json 7 8 end 9 end 34
35. SPECIFY DEFAULT VERSION 1 module Starbucks 2 class API < Grape::API 3 prefix 'starbucks' 4 version 'v2' 6 format :json 7 8 end 9 end 35
36. SPECIFY FORMAT 1 module Starbucks 2 class API < Grape::API 3 prefix 'starbucks' 4 version 'v2' 6 format :json 7 8 end 9 end 36
37. DEFINE A RESOURCE And the action to be taken 37
38. 1 module Starbucks 2 class API < Grape::API 3 resource :orders do 4 desc "get a order" 5 get '/:id' do 6 order = Order.where(id: params.id).first 7 8 unless order 9 throw :error, status: 404, message:"not found" 11 end 12 13 header "Last-Modified", order.updated_at 15 order 16 end 17 end 18 end 19 end 38
39. 1 module Starbucks 2 class API < Grape::API 3 resource :orders do 4 desc "get a order" 5 get '/:id' do 6 order = Order.where(id: params.id).first 7 8 unless order 9 throw :error, status: 404, message:"not found" 11 end 12 13 header "Last-Modified", order.updated_at 15 order 16 end 17 end 18 end 19 end INLINE DOCS 39
40. WEBMACHINE https://github.com/seancribbs/webmachine-ruby by @seancribbs of Basho port of the Erlang library 40
41. Little Weird but Fun 41
42. HTTP AS STATEMACHINE 42
43. HTTP SPEC MODELLED AS A STATE MACHINE 43
44. EXECUTEABLE HTTP SPECS 44
45. MINDBLOWN 45
46. HTTP = PROTOCOL AS S.M 46
47. GREAT FOR LEARNING HTTP 47
48. BEFORE/AFTER HOOKS LIKE ACTIVERECORD 48
49. AASM IN RAILS MODELS OR 49
50. STATE IS DETERMINED BY REQUEST AND CALLBACKS 50
52. resource_exists? service_available? is_authorized? forbidden? allow_missing_post? malformed_request? uri_too_long? known_content_type? valid_content_headers? valid_entity_length? options allowed_methods known_methods delete_resource delete_completed? post_is_create? create_path base_uri process_post content_types_provided content_types_accepted charsets_provided languages_provided language_chosen encodings_provided variances 36 CALLBACKS 52
53. RICH CALLBACKS vs ActiveRecord 53
54. THESE CALLBACKS 54
55. FULFILL DIFFERENT ROLES 55
56. STATE GUARDS 56
57. EXAMPLE 57
58. IRCTC API DOWN BEFORE 5 AM 58
59. 1 class SeeOrder < Webmachine::Resource 2 def service_available? 3 # HTTP/1.1 503 Service Unavailable 4 # Retry-After: Fri, 21 Jun 2013 04:30:00 GMT 5 now = Time.now 6 morning = now.at_5_morning 7 if now < now.at_5_morning 8 response.headers['Retry-After'] = 9 morning.httpdate 10 false 11 else 12 true 13 end 14 end 15 end 59
60. CAN WRITE A BEFORE FILTER IN RAILS 60
61. BUT WEBMACHINE defines 61
62. CONVENTION 62
63. SERVICE_AVAILABLE? callback is called by convention 63
64. 503 SERVICE AVAILABLE and returns by convention 64
65. ONE MORE EXAMPLE 65
66. 1 class SeeOrder < Webmachine::Resource 2 def content_types_provided 3 [["application/json", :to_json]] 4 end 5 6 # Does the resource exist? Returning a falsey 7 # value (false or nil) 8 # will result in a '404 Not Found' response. 9 def resource_exists? 10 order 11 end 12 13 def to_json 14 order.to_json 15 end 16 end 66
67. CONVENTIONS AGAIN webmachine drives your code. ie. vs Rails convention = http status code and control-flow 67
68. HANDLE POST REQUEST 68
69. FIT YOUR CODE INTO HTTP CALLBACKS 69
70. 1 class OrderController < ApplicationController 2 respond_to :json 3 # before_filter :find_order 4 # before_filter :resource_exists! 5 6 def show 7 @order = Order.find(params[:id]) 8 if @order 9 respond_with(@order) 10 else 11 # have to explicitly specify the http code 12 # and hook-in the callback 13 head 404 14 false 15 end 16 end 17 end 70
71. DISADVANTAGES 71
72. ROUTER IS UNDERPOWERED 72
74. 1 MyApp = Webmachine::Application.new do |app| 2 app.routes do 3 add ['<URL>'], ResourceClass do |request| 4 request.method == "GET" && request.query["id"] 5 end 6 end 7 end 74
75. NOT BUILT FOR RACK 75
76. DEMO 76
77. RETRO-SPECTIVE 77
78. “Webmachine is an executable model for HTTP, while Grape is a DSL for RESTful APIs.” - @dblock 78
79. “In Grape you have to be disciplined about those API methods - they should represent resources, not RPC service endpoints” - @dblock 79
80. “In Webmachine you implement resource callbacks, while in Grape you use procedural logic within the API method implementation” - @dblock 80
81. Grape is a Rack framework while Webmachine is its own framework 81
82. Would Use Grape for Production code. But put understand Webmachine code 82
83. CELLULOID FOR RPC https://github.com/celluloid/dcell 83
84. WHY RPC 84
85. NO CLIENT 85
86. HTTP IS BULKY 86
87. BINARY SERIALIZATION MessagePack 87
88. LIKE DRB but much better 88
89. CONCURRENCY 89
90. SUPERVISION handles failure pretty well 90
91. DEMO 91
92. FIN. @deepak_kannan http://codemancers.com 92