Some tips and patterns on how to design elegant Ruby APIs

1. Elegant APIs
Why your methods
should never
go missing
Presented by Andrew Timberlake

2. Elegant APIs
variable arguments
method_missing
blocks
instance_eval

3. Elegant APIs
variable arguments
method_missing
blocks
instance_eval

4. variable arguments Elegant APIs
method_missing
blocks
instance_eval

5. variable arguments Elegant APIs
def method(arg1)
#...
end

6. variable arguments Elegant APIs
def method(arg1 = 1)
#...
end

7. variable arguments Elegant APIs
def method(arg1 = 1, arg2 = 2)
#...
end

8. variable arguments Elegant APIs
def method(opts = {})
options = {:arg1 => 1,
:arg2 => 2}.merge(opts)
#...
end

9. variable arguments Elegant APIs
def method(opts = {})
options = {:arg1 => 1,
:arg2 => 2}.merge(opts)
#...
end
method :arg2 => 3

10. variable arguments Elegant APIs
#Active Record
User.create(:first_name => 'Andrew',
:last_name => 'Timberlake')

11. Elegant APIs
variable arguments
method_missing
blocks
instance_eval

12. method_missing Elegant APIs
variable arguments
blocks
instance_eval

13. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
http://github.com/andrewtimberlake/css

14. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
http://github.com/andrewtimberlake/css

15. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
http://github.com/andrewtimberlake/css

16. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
puts body['background-color'] #=> #FFF
http://github.com/andrewtimberlake/css

17. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
puts body['background-color'] #=> #FFF
puts body.background #=> background:#FFF
http://github.com/andrewtimberlake/css

18. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
puts body['background-color'] #=> #FFF
puts body.background #=> background:#FFF
puts body.background_color #=> #FFF
http://github.com/andrewtimberlake/css

19. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
puts body['background-color'] #=> #FFF
puts body.background #=> background:#FFF
puts body.background_color #=> #FFF
puts body.backgroundColor #=> #FFF
http://github.com/andrewtimberlake/css

20. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
puts body['background'] #=> background:#FFF
puts body[:background] #=> background:#FFF
puts body['background-color'] #=> #FFF
puts body.background #=> background:#FFF
puts body.background_color #=> #FFF
puts body.backgroundColor #=> #FFF
puts body.background.color #=> #FFF
http://github.com/andrewtimberlake/css

21. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
body.background.image = 'url(image.png)'
http://github.com/andrewtimberlake/css

22. method_missing Elegant APIs
css = CSS::Parser.parse("body { background: #FFF }")
body = css['body']
body.background.image = 'url(image.png)'
puts body.background #=> background:#FFF url(image.png)
http://github.com/andrewtimberlake/css

23. method_missing Elegant APIs
def method_missing(method_name, *args, &block)
get(normalize_property_name(method_name.to_s))
end
http://github.com/andrewtimberlake/css

24. method_missing Elegant APIs
def respond_to?(method_name, include_private = false)
property_name = normalize_property_name(method_name.to_s)
default_properties.keys.include?(property_name)
end
http://github.com/andrewtimberlake/css

25. method_missing Elegant APIs
def respond_to?(method_name, include_private = false)
property_name = normalize_property_name(method_name.to_s)
default_properties.keys.include?(property_name) || super
end
http://github.com/andrewtimberlake/css

26. method_missing Elegant APIs
def method_missing(method_name, *args, &block)
property_name = method_name.to_s
if respond_to?(method_name)
property_name = normalize_property_name(property_name)
get(property_name)
end
end
http://github.com/andrewtimberlake/css

27. method_missing Elegant APIs
def method_missing(method_name, *args, &block)
property_name = method_name.to_s
if respond_to?(method_name)
property_name = normalize_property_name(property_name)
get(property_name)
else
super
end
end
http://github.com/andrewtimberlake/css

28. method_missing Elegant APIs
def method_missing(method_name, *args, &block)
property_name = method_name.to_s
setter = property_name.chomp!('=')
if respond_to?(method_name)
property_name = normalize_property_name(property_name)
if setter
@properties[property_name] = ...
else
get(property_name)
end
else
super
end
end
http://github.com/andrewtimberlake/css

29. Elegant APIs
variable arguments
method_missing
blocks
instance_eval

30. blocks Elegant APIs
variable arguments
method_missing
instance_eval

31. blocks Elegant APIs
ec2 = Awsum::Ec2.new('123456', '654321')
ec2.run_instances 'ami-123456'
http://github.com/internuity/awsum

32. blocks Elegant APIs
ec2 = Awsum::Ec2.new('123456', '654321')
ec2.run_instances 'ami-123456'
region = ec2.region('eu-west')
region.run_instances 'ami-123456'
region.create_volume 'eu-west-1a'
region.allocate_address
http://github.com/internuity/awsum

33. blocks Elegant APIs
region = ec2.region('eu-west')
region.run_instances 'ami-123456'
region.create_volume 'eu-west-1a'
region.allocate_address
ec2.region('eu-west').use do |region|
region.run_instances 'ami-123456'
region.create_volume 'eu-west-1a'
region.allocate_address
end
http://github.com/internuity/awsum

34. blocks Elegant APIs
ec2.region('eu-west').use do |region|
run_instances
end
class Awsum::Ec2::Region
def use(&block)
old_host = @ec2.host
@ec2.host = end_point
yield self
ensure
@ec2.host = old_host
end
end
http://github.com/internuity/awsum

35. blocks Elegant APIs
ec2.region('eu-west').use do |region|
region.run_instances 'ami-123456'
region.create_volume 'eu-west-1a'
region.allocate_address
end
http://github.com/internuity/awsum

36. blocks Elegant APIs
ec2.region('eu-west').use do |region|
region.run_instances 'ami-123456'
region.create_volume 'eu-west-1a'
region.allocate_address
end
ec2.region('eu-west').use do
run_instances 'ami-123456'
create_volume 'eu-west-1a'
allocate_address
end
http://github.com/internuity/awsum

37. Elegant APIs
variable arguments
method_missing
blocks
instance_eval

38. instance_eval Elegant APIs
variable arguments
method_missing
blocks

39. instance_eval Elegant APIs
ec2.region('eu-west').use do
run_instances
end
class Awsum::Ec2::Region
def use(&block)
old_host = @ec2.host
@ec2.host = end_point
instance_eval(&block)
ensure
@ec2.host = old_host
end
end
http://github.com/internuity/awsum

40. instance_eval Elegant APIs
ec2.region('eu-west').use do
run_instances
end
class Awsum::Ec2::Region
def use(&block)
old_host = @ec2.host
@ec2.host = end_point
block.arity < 1 ? instance_eval(&block) : block[self]
ensure
@ec2.host = old_host
end
end
http://github.com/internuity/awsum

41. instance_eval Elegant APIs
class Awsum::Ec2::Region
def use(&block)
if block_given?
begin
old_host = @ec2.host
@ec2.host = end_point
block.arity < 1 ? instance_eval(&block) : block[self]
ensure
@ec2.host = old_host
end
else
@ec2.host = end_point
self
end
end
end
http://github.com/internuity/awsum

42. instance_eval Elegant APIs
ec2.region('eu-west').use do
run_instances
end
http://github.com/internuity/awsum

43. instance_eval Elegant APIs
ec2.region('eu-west').use do
run_instances
end
ec2.region('eu-west') do
run_instances
end
http://github.com/internuity/awsum

44. instance_eval Elegant APIs
ec2.region('eu-west') do
run_instances
end
def region(region_name)
region = regions(region_name)[0]
end
http://github.com/internuity/awsum

45. instance_eval Elegant APIs
ec2.region('eu-west') do
run_instances
end
def region(region_name, &block)
region = regions(region_name)[0]
if block_given?
region.use(&block)
else
region
end
end
http://github.com/internuity/awsum

46. instance_eval Elegant APIs
class Awsum::Ec2::Region
def method_missing(method_name, *args, &block)
use do
@ec2.send(method_name, *args, &block)
end
end
def respond_to?(method_name,
include_private = false)
@ec2.respond_to?(method_name, include_private)
|| super
end
end
http://github.com/internuity/awsum

47. Elegant APIs
Inspiration
(recommended reading)
Ruby Best Practices
http://ruby best practices book.com
Practicing Ruby newsletter
http://letter.ly/practicing-ruby
Thanks Gregory Brown

48. Elegant APIs
Thank you
twitter: @atimberlake
email: andrew@andrewtimberlake.com
web: http://andrewtimberlake.com
code: http://github.com/andrewtimberlake