Is your helper library opinionated enough? (PyTexas 2014)

It's a constant debate.

How do you build a helper library?

At one end of the spectrum we have Runscope CEO John Sheehan who thinks that helper libraries are evil and shouldn't exist at all. At the other we find helper libraries that don't look or smell anything like the API. And somewhere in the middle we have helper libraries that are so close to the API itself that they are nothing more than a thin veneer.

Which is better? Who’s right? The real question to me is how idiomatic should a helper library be? Should a Django library make a Django developer feel comfortable, or should she have to read the API docs to understand how it works? Should a Python library look RESTful, or should it look like a hierarchy of classes?

At our company, we maintain two libraries. They both have advantages and disadvantages, they appeal to different developers, and sometimes even the same developer at different times.

Transcript

1. Is your Helper Library Opinionated Enough? Paul  Murphy   paul@clarify.io   @prmurphy  
2. In the beginning…
3. Things were great at first
4. Until…
5. Until…
7. The helper library continuum
8. The three orthodoxies
9. John Sheehan is a nudist John Sheehan
10. Nudism pros • Performance • Reliability • Flexibility • No extra work!
11. Nudism cons • Lose tire kickers • Lose prototypers • Lose newbies • A lot of work!
12. No helper libraries • No bugs • No mystery • No fun • No clients
13. Some stats • API raw: • Python: • PHP: • Node: • Other: 40% 30% 10% 10% 10%
14. Set the User-Agent def _get_headers(): user_agent = __api_lib_name__ + '/' + __version__ + '/' + PYTHON_VERSION return {'Authorization': 'Bearer ' + KEY, 'User-Agent': user_agent, 'Content-Type': ’…'}
16. John Sheehan is a nudist Me Always cold. I like to help. Really. (He’s a control freak.)
17. Some polar explorer examples • Hiding scale • Hiding complexity
18. Hiding Scale class BundleList: def bl_map(func): has_next_page = True while has_next_page: …
19. Hiding Scale GET /v1/bundles?limit=2
20. Hiding Scale { "total": 8, "limit": 2, "_class": "Collection", "_links": { "self": { "href": "/v1/bundles?limit=2" }, "items": [ { "href": "/v1/bundles/3fbca3fe3678495fb08fe939dbe4f1cd" }, { "href": "/v1/bundles/2a112c5b3e944802b932b0ddbf068c37" } ], "first": { "href": "/v1/bundles?limit=2&iterator=L1aa00000000000000000000000000000000h0" }, "last": { "href": "/v1/bundles?limit=2&iterator=L1ab00000000000000000000000000000000h0" }, "next": { "href": "/v1/bundles? limit=2&iterator=L1aa2a112c5b3e944802b932b0ddbf068c37h1396986421855" } } }
21. Hiding Complexity class Bundle: def is_indexed(): # check media status … # check keyword status … # check topic status …
22. Hiding Complexity GET /v1/bundles/ 3fbca3fe3678495fb08fe939dbe4f1cd? embed=metadata&embed=tracks
23. { "id": "3fbca3fe3678495fb08fe939dbe4f1cd", "type": "audio", "name": "The Future of Women in Flying", "created": "2014-04-08T18:37:35.420Z", "_class": "Bundle", "_links": { ... }, "_embedded": { "clarify:tracks": { "bundle_id": "3fbca3fe3678495fb08fe939dbe4f1cd", "status": "ready", "created": "2014-04-08T18:37:35.425Z", "updated": "2014-04-08T19:05:13.719Z", "tracks": [ { "track": 0, "media_url": "http://archive.org/download/ Greatest_Speeches_of_the_20th_Century/TheFutureofWomeninFlying_64kb.mp3", ... "status": "ready", } ], ... }, "clarify:metadata": { ... } } }
24. John Sheehan is a nudist Polar explorer pros •  No friction •  PnP with native modules •  Can absorb API changes •  Reference implementation •  Fewer customer bugs!
25. John Sheehan is a nudist Polar explorer cons •  Bugs •  Hides information •  Wrong tradeoffs •  Often out of sync •  So much extra work!
27. Ivo Rothschild Likes to wear clothes. Not too many, and not too few. Just the right amount.
28. Some Goldilocks examples • A Goldilocks function signature • A Goldilocks result
29. Function signature def create_bundle(name='PyTexas', media_url=None, audio_channel=None, metadata=None, notify_url=None): POST /v1/bundle [post data]
30. Result { "id": "ee1", "_class": "Ref", "_links": { "self": { "href": "/v1/bundles/XX" }, "curies": [ { "href": "/docs/rels/{rel}", "name": "PyTexas", "templated": true } ], "clarify:metadata": { "href": "/v1/bundles/XX/metadata" }, "clarify:tracks": { "href": "/v1/bundles/XX/tracks" } } } { u'id': u'ee1' u'_class': u'Ref', u'_links': { u'self': { u'href': u'/v1/bundles/XX' }, u'curies': [ { u'href': u'/docs/rels/{rel}', u'name': u'PyTexas', u'templated': True } ], u'clarify:metadata': { u'href': u'/v1/bundles/XX/metadata' }, u'clarify:tracks': { u'href': u'/v1/bundles/XX/tracks' } }, }
31. John Sheehan is a nudist Goldilocks Pros • Performance • Familiarity • Don’t break when API changes • Fewer dev bugs
32. Goldilocks Cons • Bugs • Have to read all the docs • Extra work!
33. These guys never go away
34. But if you’re running an API business…
35. Thank  you!   Paul  Murphy   paul@clarify.io   @prmurphy  
36. Any  Ques:ons?   PS. We’re hiring! Paul  Murphy   paul@clarify.io   @prmurphy