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 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. Indeed there were restrictions based based on geography, and your business profile (risk, compliance etc). However, it did mean investing in ONE technical integration, and that it would work seamlessly with 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 of API docs are valued by buyers and decision makers, but it was fun reflecting on this.