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.

Nice explanation of developer pain points

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.

State of the API 2019

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)

API Product vs API Service

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):

Amazon’s internal API success


History of APIs

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”

There are awards for developer portal DX

..And who are the stakeholders behind the development of those award-winning developer portals?

Developer Portal stakeholders

And, what are some criteria by which to judge those docs?

Questions your API docs must answer

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.

Pushing the API docs conversation forward

How to measure API success?

First off, how do they make money, what are the business models?

API business models

Then how do we measure the KPIs? (key performance indicators):

API Ops: measure

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!

Cross the Chasm

(Ok, I bet you really have more like 10 minutes) here are some tips for getting the developer experience (DX) right:

Developer Portal Design Tips

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).

Business of SaaS