APIs and API docs — what I took for granted
A fish in new waters starts to notice things it took for granted after swimming in new waters. These are the three points I have come to realize weren’t “normal/expected” about payment API docs, after leaving Stripe.
- Publicly available API docs aren’t the norm
- One united API is not the norm
- Clear, detailed explanations in API docs are not the norm
1. Publicly available API docs aren’t the norm
I’m used to searching a company’s API docs to understand what’s available, whether it’s clear, and how things might work. While I’ve known that API docs sometimes are sent over email, and sometimes secure mail, now I’ve fully digested the surreal process of:
- Emailing someone for the API doc(s)
- Waiting for that person to get someone else to send you the doc via a secure link, at some point.
- Or give you access to some sort of portal to review the docs
The process can take up to a month vs immediately accessed and reviewed online. It feels befuddling (would love to be corrected) on why the API docs have to be delivered via a secure mail, because what exactly is so proprietary (isn’t the secret sauce in the API architecture at the back end?). Regardless, something to buffer for if you’re doing a technical due dilligence.
2. One united API is not a norm
One thing I enjoyed about selling Stripe is that I could honestly say, that if you integrated the API, you could access all the payment methods that the docs said you could. It is truly one API. Yes you will still face restrictions based based on geography, and your business profile (risk, compliance etc). However, it does mean that you invest in ONE technical integration, and it will work if you expand it into other products like recurring payments, or offline payments etc. This saves time versus spending additional technical resources to scrutinize and integrate additional APIs. It’s far more efficient for global expansion.
3. Clear, detailed explanations in API docs are not the norm
Detailed explanations refer to information within the API docs to guide a successful integration. A non exhaustive list could be — parameter descriptions, code samples, guides and educational resources in the API library. For example, for every payment method, explaining which countries, what disputes, how to handle refunds, payouts — thoughtfully distilling essential information for the business using the APIs. I’ve since learned these explanations do not always exist, and that sometimes more meetings are required to discuss these docs, versus them being self explanatory.
Overall, it’s enjoyable to to step back (a fish swimming in new waters) and realize that what I mentally held as “normal/given” — public facing docs, one API integration, clearly written and descriptive docs — aren’t the norm. This post does not cover if the three characteristics are actually valued by payment buyers and decision makers (might discuss this another time), but it was fun reflecting on this.