API design for gem authors (and users) Ruby applications are becoming more complex and unwieldy (think MonoRails). An increasing number of us are trying to address this by separating our apps into gems without knowing best practices on how to write APIs or how to manage dependencies and versioning. The discussion we often have around good APIs should not stop with Ruby OO design, but should also consider the public APIs of gems. This talk is intended for gem authors and users. It will share though many practical examples using the Ruby driver to MongoDB 1) Principles of good gem API design, 2) How to make your gem API optimal for users and how to best use the API of a gem, 3) Guidelines for introducing and anticipating gem API changes and managing dependencies.

1. Gem API design
for authors
(and users)
Emily Stolfo
Ruby Engineer at
@EmStolfo
, Adjunct Faculty at Columbia

2. Many of us
have become
gem authors.
(whether we like it or not)

3. Our code served a
browser and a
mouse.

4. Now our code serves
other developers.

5. Is it just me, or does ____ seem like a
poorly designed piece of software; lots
of magic, poor OOP design, poor
documentation, etc.? I appreciate the
contribution to open source, though.

6. gem API design is
UX design

7. The UX Fund
experiment

8. Great user
experience is
directly reflected
in stock price.

9. RubyGems

10. Developer Experience
(DX) team
Drivers
Docs
Tools

11. gem API design is
UX design

12. USERS

13. Know your users.*
* open source users or your colleagues

14. Listen in.

15. Read blogs.
Use twitter.
Talk to users.
Give presentations.

16. Establish trust.

17. USE
SEMANTIC
VERSIONING

18. Involve
super users.

19. UX DESIGN
CONCEPTS

20. Consistency
Simplicity
Mapping

21. Consistency
Simplicity
Mapping

22. Consistency
Simplicity
Mapping

23. Consistency
Simplicity
Mapping

24. 3 Consistency Considerations
4 Simplicity Suggestions
5 Mapping Mantras

25. Consistency
Considerations

26. 1. Consider
consistent naming.

27. 2. Consider
consistent style.

28. 3. Consider
consistent behavior.

29. Simplicity
Suggestions

30. 1. Give classes a
single responsibility.

32. 2. Hide
implementation
details.

33. attr_reader :name, :connection
...
protected
...
private
...

34. 3. Be frugal with
helpers.

35. Index creation
X
@posts.text_index(‘title’)
@posts.create_index({ ‘title’ => Mongo::TEXT })

36. 4. Design your API
first.

37. new driver “fluent API”
X
@orders.find_and_modify(
:query => {},
:new => true,
:update => {:$set =>
{:processed => true})
@orders.find({}).
update_one_then_get({:$set =>
{:processed => true})

38. Mapping
Mantras

39. 1. Monkey-patching
is mean.

40. refinements
refine String do
...
end

41. 2. Side effects are
surprising.

42. Mutating opts
X
def map_reduce(map, reduce, opts={})
...
raw = opts.delete(:raw)
...
def map_reduce(map, reduce, opts={})
opts = opts.dup
raw = opts.delete(:raw)
...

43. 3. Requiring
method chaining
is impolite.

44. X
@client.pool_manager.primary_pool
@client.primary

45. 4. Informative error
messages are
imperative.

46. mongoid

47. 5. Documentation
without hesitation.

48. # inline comments

49. Documentation tools

50. README.md

51. Getting started
http://code.dblock.org/your-first-ruby-gem

53. Think like a
UX designer.

54. Get social.
© JEG2

55. Talk to me about
the Ruby driver :)
Emily Stolfo
emily@mongodb.com
@EmStolfo