4 ms·

Ask HN: Why is Stripe API documentation lacking so badly?

11 points by johanlaidlaw 9y ago

I really enjoy working with all parts of Stripe, except for reading their API documentation because it is lacking so much.

nodex-alex 9y ago
Lacking what exactly? I've never had a problem finding what I need from it
zapperdapper 9y ago
You could file a bug report with Stripe letting them know where you think they could improve their docs.
ruairidhwm 9y ago
I've found their API docs to be extremely helpful in the past. What do you find to be lacking? The team are very responsive, so as zapperdapper mentioned, I'm sure they'd welcome a bug report with details of what you're having trouble with.
ezekg 9y ago
That’s something I haven’t heard before. I’m sitting here thinking Stripe pioneered good, in-depth API documentation. What exactly do you feel is lacking? I’ve been using Stripe for years and haven’t had any issues with their docs.
mod 9y ago
I hold the position that Stripe has truly great documentation and should be held up as a standard for other people writing documentation to work towards. I haven't found it to be lacking for any of my use cases.
git-pull 9y ago
Easy snags when learning Stripe's API: 1. Internalizing core objects, like the Customer, Card, Tokens, and Source. And Plans / Subscriptions. Card/Source can feel ambiguous, since the API lookups are similar. 2. Order for creating / pulling up some objects. Customer's can attach a source upon creation, but can also attach it later. But you can't just look up all cards - you retrieve a card by looking up the customer first. This helps later on if your user wants to update their billing info. Think about it: You pull up the customer first. Then a customer has cards they can delete, update, or add. Plans must be created before subscriptions. That's another huge favor. Because on your front end, you can have the user switch between plans and have a consistent selection site-wide. Rather than just declaring an arbitrary price. 3. Understanding the difference between stripe.createSource (a reusable billing object) and stripe.createToken (a temporary billing object) [1] 4. Getting effective coverage in billing systems. Requires a ton of mocks. In order to simulate the responses to create the mocks, you have to play with the test API to get the desired outputs. The docs don't give you that. In fact, stripe-mock [2] doesn't give you all the possible scenarios. So there's going to be a lot of time spent "bullet proofing" a subscription system. Especially if it's self-service. I'd estimate it took about 1.5 months to get it fully working when I did it at a startup. The second time around, it's taking more time since I want to be able reusable enough to use on other websites / clients. Maybe 2-2.5 months. [1] https://stripe.com/docs/sources/cards#create-source https://stripe.com/docs/sources/cards#create-source [2] https://github.com/stripe/stripe-mock https://github.com/stripe/stripe-mock
dmlittle 9y ago
Are you looking at their docs[1] or their API docs[2]? While both are helpful, they solve slightly different needs. [1] https://stripe.com/docs https://stripe.com/docs [2] https://stripe.com/docs/api https://stripe.com/docs/api
maxencecornet 9y ago
>it is lacking so much. Stripe API documentation is the best i've ever seen, I really don't see what could be improved Do you have any exemples in mind ?
- johanlaidlaw 9y ago
  I wasn't clear - I really like the documentation, but my browser lacks (a lot) every time I visit the docs page. But must be my computer, since no one else has this problem
  - metafunctor 9y ago
    The word you're looking for is probably “lag”, not “lack”.
someotheridiot 9y ago
Have you ever tried to use PayPal's documentation? Might make you feel better about Stripe :)
johanlaidlaw 9y ago
I'm glad to hear no one else has this problem. Must be isolated to my computer then. The docs are written really well and it is super clear how to use it. It is just my computer that hangs everytime I visit that page

11 points by johanlaidlaw 9y ago

I really enjoy working with all parts of Stripe, except for reading their API documentation because it is lacking so much.

nodex-alex 9y ago

Lacking what exactly? I've never had a problem finding what I need from it

zapperdapper 9y ago

You could file a bug report with Stripe letting them know where you think they could improve their docs.

ruairidhwm 9y ago

I've found their API docs to be extremely helpful in the past. What do you find to be lacking? The team are very responsive, so as zapperdapper mentioned, I'm sure they'd welcome a bug report with details of what you're having trouble with.

ezekg 9y ago

That’s something I haven’t heard before. I’m sitting here thinking Stripe pioneered good, in-depth API documentation. What exactly do you feel is lacking? I’ve been using Stripe for years and haven’t had any issues with their docs.

mod 9y ago

I hold the position that Stripe has truly great documentation and should be held up as a standard for other people writing documentation to work towards. I haven't found it to be lacking for any of my use cases.

git-pull 9y ago

Easy snags when learning Stripe's API: 1. Internalizing core objects, like the Customer, Card, Tokens, and Source. And Plans / Subscriptions. Card/Source can feel ambiguous, since the API lookups are similar. 2. Order for creating / pulling up some objects. Customer's can attach a source upon creation, but can also attach it later. But you can't just look up all cards - you retrieve a card by looking up the customer first. This helps later on if your user wants to update their billing info. Think about it: You pull up the customer first. Then a customer has cards they can delete, update, or add. Plans must be created before subscriptions. That's another huge favor. Because on your front end, you can have the user switch between plans and have a consistent selection site-wide. Rather than just declaring an arbitrary price. 3. Understanding the difference between stripe.createSource (a reusable billing object) and stripe.createToken (a temporary billing object) [1] 4. Getting effective coverage in billing systems. Requires a ton of mocks. In order to simulate the responses to create the mocks, you have to play with the test API to get the desired outputs. The docs don't give you that. In fact, stripe-mock [2] doesn't give you all the possible scenarios. So there's going to be a lot of time spent "bullet proofing" a subscription system. Especially if it's self-service. I'd estimate it took about 1.5 months to get it fully working when I did it at a startup. The second time around, it's taking more time since I want to be able reusable enough to use on other websites / clients. Maybe 2-2.5 months. [1] https://stripe.com/docs/sources/cards#create-source https://stripe.com/docs/sources/cards#create-source [2] https://github.com/stripe/stripe-mock https://github.com/stripe/stripe-mock

dmlittle 9y ago

Are you looking at their docs[1] or their API docs[2]? While both are helpful, they solve slightly different needs. [1] https://stripe.com/docs https://stripe.com/docs [2] https://stripe.com/docs/api https://stripe.com/docs/api

maxencecornet 9y ago

>it is lacking so much. Stripe API documentation is the best i've ever seen, I really don't see what could be improved Do you have any exemples in mind ?

johanlaidlaw 9y ago
I wasn't clear - I really like the documentation, but my browser lacks (a lot) every time I visit the docs page. But must be my computer, since no one else has this problem
- metafunctor 9y ago
  The word you're looking for is probably “lag”, not “lack”.

someotheridiot 9y ago

Have you ever tried to use PayPal's documentation? Might make you feel better about Stripe :)

johanlaidlaw 9y ago

I'm glad to hear no one else has this problem. Must be isolated to my computer then. The docs are written really well and it is super clear how to use it. It is just my computer that hangs everytime I visit that page