4 ms·
(I work at Stripe.) As an API author, I think your goal should be to make interacting with your API as simple and robust as possible. The downside with just re
by gdb 14y ago
(I work at Stripe.)
As an API author, I think your goal should be to make interacting with your API as simple and robust as possible. The downside with just recommending off-the-shelf HTTP clients is that there's always a ton of logic (whether request formatting, error handling, or turning responses into first-class objects) that the vast majority of consumers of your API want and will have to write on their own. If you look at the internals of our bindings, a lot of the logic is around understanding exceptions (https://github.com/stripe/stripe-ruby/blob/master/lib/stripe.rb#L244 https://github.com/stripe/stripe-ruby/blob/master/lib/stripe...) or interstanding semantics of our API (https://github.com/stripe/stripe-ruby/blob/master/lib/stripe.rb#L214 https://github.com/stripe/stripe-ruby/blob/master/lib/stripe...), which are tasks that would take a newcomer a lot of time to get get spun up on.
There will always be frameworks where your bindings don't work (e.g. our Ruby bindings aren't compatible with EventMachine) or paradigms that they violate (e.g. using error return values in PHP rather than throwing exceptions). That's actually ok -- just because you can't support everyone doesn't mean you should support no one. Instead, we put a lot of effort into making our bindings compatible with as broad of a range of environments as possible (e.g. https://github.com/stripe/stripe-python/blob/master/stripe/__init__.py#L28 https://github.com/stripe/stripe-python/blob/master/stripe/_...).
So my advice would be write bindings which convert the semantics of your API to the consumer's language, but which constrain the consumer's application as little as they can. Even if people end up having to use a lower-level abstraction to talk to your API, they can probably steal code or ideas from what you've written.
- zemaj 14y agoThat's great advice, thanks! Hadn't thought about how it improves the ability of the vast majority of developers to get up to speed with handling edge cases. That's a really good point. Perhaps I'll start with thin wrappers and progressively add deeper bindings to get the best of both worlds.