Recently I had some time to kill, and I went on a wikipedia-spiral type reading tour of the current state of the API industry. (Inspired, I suppose, by the realization that GraphQL is now a thing).
Here are some of my favorite articles from my tour:
API Developer pain points
Hint: lack of docs is high up there!
But my own takeaway after some reading is that a LOT of the undocumented APIs are internal, behind corporate firewalls.
APIs that are being sold externally are more likely to have docs.
State of the API industry
A takeaway is that there’s tremendous interest, but it’s still the wild west in terms of standardizing development and maintenance.
It’s also very interesting to understand the difference between API solutions (putting fresh lipstick on old services behind your corporate firewall to break down department silos) vs API products (selling API services externally)
While we’re at it, how did we get here?
A little history is invaluable (I had no idea it had so much to do with Amazon (both in selling cloud computing power, and in Bezos mandating that the company use APIs internally):
Fun fact: I learned from an API strategist that Capitol One is another big company besides Amazon that has thousands of internal APIs. (And sorry, but I’m a customer and…their web AND mobile experiences are constantly breaking on me! It makes me wonder if they’re keeping my $$ safe!)
Cool, there are awards for API docs!
Or for developer experience, if you want to broaden the definition of “docs”
..And who are the stakeholders behind the development of those award-winning developer portals?
And, what are some criteria by which to judge those docs?
And what will the best docs of the future look like? I love the idea of built-in visualizations of API responses included in interactive API docs, rather than simple json responses.
How to measure API success?
First off, how do they make money, what are the business models?
Then how do we measure the KPIs? (key performance indicators):
FYI API Ops is a valuable education resource in general on how to develop APIs with a real methodology.
How to convert developers to your API?
You only have 3 minutes!
(Ok, I bet you really have more like 10 minutes)
..so here are some tips for getting the developer experience (DX) right:
And while we’re at it, I think we can draw a ton of parallels between APIs as a product and SaaS business models. I never REALLY understood the “long slow SaaS ramp of death” till I read this; it’s mind blowing stuff… and it helps me understand that low-touch API products need to be optimized aggressively for getting the user to trial (but maybe high-touch API products don’t need onboarding optimization as much).