
Building Stripe's API - boucher
http://amberonrails.com/building-stripes-api/
======
zemaj
This is a great post. I'm currently building an API that's really inspired by
Stripe's API. I'm trying to mimic a lot of these elements, from the easy
authentication through to the really useful error messages.

One of the things I'm not so sure about is the local bindings for each
language. I'm tempted to just use off-the-shelf HTTP clients or a very thin
wrapper in each language and write code snippets based on them. I'm not sure I
see the value in writing full client bindings - I've often found it harder to
use in many cases when I use these 'opinionated' bindings in the past. You
often end up with a choice of entirely following the libraries views on error
handling or digging around and breaking upgrades by modifying these libraries
directly. I've always preferred much thinner wrappers that have no knowledge
of the underlying API calls. Would love more opinions!

~~~
gdb
(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...](https://github.com/stripe/stripe-
ruby/blob/master/lib/stripe.rb#L244)) or interstanding semantics of our API
([https://github.com/stripe/stripe-
ruby/blob/master/lib/stripe...](https://github.com/stripe/stripe-
ruby/blob/master/lib/stripe.rb#L214)), 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/_...](https://github.com/stripe/stripe-
python/blob/master/stripe/__init__.py#L28)).

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
That'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.

------
dm8
I personally think API design should be done by someone who has background in
both UX and engineering. Even though you know your audience is going to
technical, you'll eventually have people across the spectrum from noobs to
pros using your APIs.

~~~
kevinburke
I disagree. As a programmer every function signature you write is an interface
to the code inside. API design is a slightly higher-level version of this. I
would expect good engineers to be able to design good API's, it's a natural
extension of something they should be good at anyway.

~~~
m12k
Engineering and UX design are both examples of communication. When I write
code I communicate with multiple audiences in mind - the compiler, my current
and future colleagues, and future versions of me, that might not remember what
this variable is, so better name it meaningfully. Similarly I communicate with
my employers about what they want me to develop, and I communicate with our
users, to help them understand what this thing that I coded does, and how that
is beneficial to them.

I find that the best engineers (indeed the best people in any role) are the
best communicators, who are constantly aware of the many audiences that they
are communicating with and are always weighing these many different needs. A
good engineer is an ambassador between the technical and non-technical.

------
danso
Great explanatory post. I was wondering if dog-fooding would come up but I
guess Stripe is one online service in which dog-fooding -- in terms of
providing views of the service content -- would be non-straightforward.

Also, who else thought the domain name referred to a new client-side framework
for RoR? :)

~~~
boucher
Though perhaps not as dog-fooding as some other projects, we do build (almost)
all of our dashboard on top of our API. This was one of my first goals at
Stripe, and I think it's been a huge win for us. We also have a couple of
employees who run a real business with Stripe.

------
ajtaylor
Fantastic post, and it's chock full of great tips!

As someone who was just finished building v1 of a REST API for $work, I wish I
had learned some of these lessons 6 months ago. I took a lot of inspiration
from Stripe and Twilio but there are so many things I'd do differently for
version 2. One advantage I do have is that our API is not consumer facing so I
didn't do as much work on the docs and example request/response as I would
have otherwise.

My favorite slide was the one showing the details of a particular POST
request. I'm not currently logging requests like this, but my eyes have been
opened now to the possibilities it brings. Just the ability to debug a
response alone would make it worth it. No more tailing apache and backend
logs!

------
goronbjorn
We looked at Stripe as a source of inspiration when we were rebuilding our
API: <http://developers.box.com/docs/>

I've always wondered how this was implemented:

> We keep a per-user version which reflects the state of the API the first
> time the user made an API request

------
TallboyOne
As someone who's just adding stripe to a rails app now, I <3 Stripe.

------
electic
I think this is a mis-leading title. It should be "Building With Stripe's
API". Unless I missed it, I didn't see any behind the scenes stuff about the
tech or infrastructure Stripe uses to build out and sustain their API.

~~~
cargo8
Don't think so... the article talks about the driving factors in the decisions
made at Stripe when designing the API that should be exposed as the product of
the company. The article isn't about how to use Stripe's API to build stuff,
it is about why they made the decisions to support and not support the
functionality they did.

