Stripe is by far the best developer experience I’ve had in my career working with third party APIs/services. The attention to detail is just second to none, and documentation is a big part of this.
1. Stripe (Best)
2. Twilio
3. Twitter (Does what it needs to do quickly)
4. Puppeteer (Amazing. Was super helpful.)
5. Google (mostly ok but could be better)
APIs I've hated working with:
1. Paypal (the worst - docs are horrible and UI is not consistent with most of the help material out there because it changes all the time. Have you tried their support? That's a beauty)
2. Facebook (same story but manageable compared to paypal)
If ever there was an example of a company with "first out of the gate" advantage leading to such a large head-start that theyy could afford to constantly give the middle finger to everyone, PayPal is it. I cannot wait for legit altternatives to catch up.
Stripe is doing pretty well, but unless they somehow tap into the casual online user they won't disrupt PayPal's stranglehold to any significant extent.
[1] https://addons.mozilla.org/en-US/firefox/addon/multi-account...
[2] https://chrome.google.com/webstore/detail/sessionbox-free-mu...
Definitely agree that the old SOAP API was/is horrific. But the XML is about as easy to work with as JSON/REST.
This actually explains a lot of other things. Like the DMV.
Mousing over the links there to see where they go, the first interesting-looking one was the supported/unsupported features list, over at https://ebaydts.com/eBayKBDetails?KBid=684. Ah, I see - a wall of text reminscent of "system requirements", except it's a list of things you don't get instead.
But then going up to https://ebaydts.com, I met with... a blank page. But it has a title, so something's blown up. I hit F12 half expecting to be met with some kind of implosion, and even then I was cynically amused: the page has `<body style="display:none;>`, with no closing quote, and while Chrome parses it properly the devtools don't, so the CSS editor leaks bits of HTML.
On the one hand my infosec-sense says there's probably some awesome stuff hiding in here... but on the other hand, between the 1000 feet of bureaucracy I'd have to all but drown to report _anything_ I found, and the tenterhooks I'd be on while poking around establishing there's anything there beyond plausible deniability... not worth it?
They have no incentive to improve their docs. They're Facebook, there's no competition at all.
Apologies for the hijack, just wanted to say thanks.
We launched a SaaS product on the 2016-03 API version. Since then[1] the API has basically changed completely around subscriptions (even the top-level objects aren't called the same anymore), to the point it would probably be easiest to just start a rewrite from scratch (which probably would take a week or two). But the fact that the old API continues to work to this day and that we have been able to rely on it and focus on other things has been amazing. New customers get to enjoy the new API while our business continues to chug along with zero modifications to the payment parts. That is impressive from both a technical and from a business point of view, and ensures we will keep using Stripe forever.
[1] Stripe provides a very detailed and customized API upgrade guide based on your current API usage https://stripe.com/docs/upgrades?since=2016-03-07#how-can-i-...
https://github.com/Kapeli/Dash-User-Contributions/issues/201...
but this project would be much easier to do by someone inside of Stripe.
I know subscriptions have been significantly rehauled since then, but this was my only gripe. Stripe was absolutely excellent back when I used it.
We wrote a blog post detailing our Stripe Billing implementation: https://www.daily.co/blog/implementing-api-billing-with-stri...
[0] https://stripe.com/partners/apps-and-extensions/accounting
e.g. just now I'm implementing webhook handling for subscriptions. So I drill down to the section that lists all the events - https://stripe.com/docs/api/events/types this is massive and I don't want to read everything, so I cmd+f to find "subscription"... oh stripes taken over my default search but no worries I can hit cmd+f again and use the browsers search... I type "sub"... now the page has jumped way up to https://stripe.com/docs/api/expanding_objects... ffuuuuu...
On the other hand, a couple mails and a quick chat on their IRC resolved most of it. But I really wish there would be a clear map/diagram of what route to take depending on what you want to achieve.
Thinking back to implementing Stripe for the first time, I remember being surprised by how painless it was. Prior to that integrating payments was something that filled me with the same kind of dread I get from dealing with legal paperwork.
I love that they've been so successful.
We had dedicated PayPal liaisons and they recommended we use a product API that wasn't fit for our task. Just goes to show even their employees can't make sense of their products and documentation.
1. Simple, distinct concepts with unambiguous names.
2. Semantics are clear, following conventions as appropriate.
3. Minimize surface area without reducing functionality.
4. Clarity and specificity of ErrorCodes and messages.
= Operational characteristics =
1. Extremely low level of 500s.
2. Low call latencies.
3. The API does what it says it does.
4. Consistency is (nearly) always within its documented SLA.
5. Do not make backwards incompatible changes.
= Social characteristics =
1. Docs are correct, up-to-date, complete, specific, and unambiguous.
2. Clearly communicate service outages and resolution timelines.
3. Seek feedback on evolving the APIs.
1. self-consistency: Every entity and operation has exactly one name, a given verb always implies the same operation, paths are always constructed the same manner
2. consistency with industry norms (eg REST)