APIs and API docs — what I took for granted

  1. One united API is not the norm
  2. 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:

  • 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

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.

Photo by Christina Morillo on StockSnap

Conclusion

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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Celine Wee

Celine Wee

Musings are my own: a collection of learnings from Payments, Go To Market, Web3, Biz Ops across Stripe, Coinbase, Twitter.