Ask HN: What is the best API documentation you have ever seen? - enjayz
======
cjbprime
Stripe API docs. There have probably been many past threads about this.

~~~
hguhghuff
Stripe started really really well with its developer, library and
documentation support. In fact I think that’s a very large part of their
initial success.

At some point they lost that focus and dropped the ball. For example for a
very long time they had no direct support for reactjs even when it was hugely
popular, instead you had to go find some third party library which is a
terrible thing to have to do for implementation of payment code.

Maybe they’re improved and started supporting actively the technologies
developers are using.

~~~
jmknoll
I think Stripe offers a great product, but I still don’t think they have
direct support for react-native, relying instead on a third-party library
which isn’t very well documented, and only implements portions of the stripe
API.

------
dccoolgai
Lodash.js every single piece is explained with complete lucidity, and even if
it weren't the examples are concise and illustrative.

~~~
danShumway
A small detail, but Lodash is also globally available on their doc page. So if
you see a piece of documentation and want to experiment with it, you just hit
Ctrl-Shift-I and start typing.

It's a tiny thing that saves me a lot of time.

------
jayflux
I do like the PostgreSQL docs, they have a human feel to them and I usually
get the answer I want pretty quickly.

[https://www.postgresql.org/docs/10/static/index.html](https://www.postgresql.org/docs/10/static/index.html)

~~~
theelous3
Huh. I've always found them to be the absolute worst docs I've ever seen. Any
simple Google search will bring me to a page full of vaguely connected things
with no particular headdings or way to quickly get the info I'm looking for.

~~~
narrowtux
They become more useful with time, i.e. when you know what to look for on a
page. But I wouldn't call them great either.

------
greenyouse
Stripe is probably the best but I think Twilio is a close second. For both the
page designs are easy to read, there are clear examples (some are even
interactive), and the sites are easy to navigate.

~~~
hyder_m29
Twilio's API and SDK references vary from practically non-existent to
completely unusable. I often have to resort to reading their SDK code to
figure out what methods to use.

------
chrisco255
Auth0's is pretty damn good. Clear docs, inline sample code...Auth0 even
inlines your credentials into the example code if you're logged in.

[1] Auth0 -
[https://auth0.com/docs/api/authentication](https://auth0.com/docs/api/authentication)

~~~
fanpuns
I thought the same about those until I tried to follow the examples. First in
ruby and then in Vue, neither worked without a lot of hacking/changes. Really
cool idea though to put the credentials in the examples.

~~~
chrisco255
That's too bad. Had good success with their Node and React examples.

------
dividuum
I really like the Lua reference manual. All on a single page (e.g.
[https://www.lua.org/manual/5.3/manual.html](https://www.lua.org/manual/5.3/manual.html)),
covers the complete syntax/semantic of the language, a few concepts as well as
its Lua and C embedding APIs. All without bells and whistles. It surely helps
that it's a relatively easy language. While I learned Lua, I basically never
had to look anywhere else for information. I guess that's what a good
documentation is supposed to aim for.

------
theWheez
Surprised I don't see Django here. I'm always relieved to come back to a
django codebase, that is the best documentation on any project or framework
I've used.

------
dasmoth
Possibly depends what you mean by "API", but I really like the SQLite
documentation with its graphical representations of the query syntax.

~~~
joezydeco
Backus-Naur diagrams are sweet. I used to covet the one that Apple put out for
Apple Pascal:

[https://www.bytecellar.com/2004/06/15/apples_pascal_s/](https://www.bytecellar.com/2004/06/15/apples_pascal_s/)

~~~
dasmoth
Oh, that poster is nice!

And thanks for giving me a name for them, too.

~~~
joezydeco
In my mind I picture Steve Jobs dropping a little acid and staring at this
poster for a few hours...

------
Jeff_Brown
Not an API, but the documentation for Haskell libraries is unbelievably good.
Here's an example[1]. This documentation is generated automatically from
source code, optionally decorated with comments using a simple syntax called
Haddock[2]. Any package, whether it's built into the Haskell Platform or
contributed by a user, has the same kind of documentation. Even if the author
includes no Haddock comments, the documentation will include the type
signatures, the hyperlinking, the instance lists, and other goodies like the
minimal set of functions needed to define an instance of a class.

[1]
[http://hackage.haskell.org/package/base-4.11.1.0/docs/Data-L...](http://hackage.haskell.org/package/base-4.11.1.0/docs/Data-
List.html) [2]
[https://www.haskell.org/haddock/](https://www.haskell.org/haddock/)

------
Kagerjay
Airtable's API. Every API document is specific to you, playing around with
GET/POST/PUT/PATCH/DELETE requests is really straightforward to understand,
even for someone that isn't familiar with how these requests normally work.

The sample json responses are also based on your data too, and the docs
showcase what those look like

------
tiagoma
Qt docs, python docs, cppreference, code synthesis odb

~~~
Silixon
Python? I find the documentation to be confusing and difficult to search. Many
of the arguments to standard functions are not explicitly documented nor do
they have obvious enough names for me to guess what they mean. As I was
learning Python over the past few years, I inevitably turned to blog posts and
Stack Overflow for clearer examples and more explicit descriptions of optional
parameters.

I'd be curious to know what you like about the Python documentation because my
experience has probably been different than yours.

~~~
AkshayD08
Absolutely. I had a hard time going through Python documentation during the
early days.

------
anoncoward111
Side note, how do I volunteer or work part time writing technical
documentation?

I feel like my writing skills and my ability to make code understandable and
explicit to other readers would be a perfecy use for producing great
documentation.

~~~
edoceo
I need some docs, would compensate, contact in my profile

~~~
anoncoward111
I emailed one of the only public and most likely guessable aliases at your
domain, please let me know if you would prefer for us to chat in a more
cryptographically secure manner.

Thanks!

------
hprotagonist
The requests package for python is nicely documented: [http://docs.python-
requests.org/en/master/](http://docs.python-requests.org/en/master/)

------
mtVessel
It's not an "API doc" in the modern sense, but the DEC VMS manuals are the
best-written tech docs I have ever seen.

------
vandershraaf
Not API, but Spark Java ([http://sparkjava.com/documentation#getting-
started](http://sparkjava.com/documentation#getting-started)) has one of the
best Java framework documentation I've ever seen. Fairly concise + it has
almost everything you need to build proper Web application using Java

------
kencausey
Common Lisp HyperSpec -
[http://www.lispworks.com/documentation/HyperSpec/Front/index...](http://www.lispworks.com/documentation/HyperSpec/Front/index.htm)

My choice is, perhaps, more indicative of taste/proclivity than anything else.

~~~
yesenadam
It also has the best motto on the internet: _The very definition of class._

------
everlier
EVRYTHNG Platform docs are extremely thorough and versatile. There're also
lots of guides and examples covering how to work with their platform. Taking
into account complexity and amount of abstractions, those are one of the best
docs i've ever read.

------
mcintyre1994
I really like the Requests quickstart docs: [http://docs.python-
requests.org/en/master/user/quickstart/](http://docs.python-
requests.org/en/master/user/quickstart/)

------
htanirs
I found sonic pi documentation engaging, easy to understand and comprehensive,
[https://sonic-pi.net/tutorial.html](https://sonic-pi.net/tutorial.html)

------
dave-f
Back in the day, the documentation for the 3DO seemed great. I was programming
on another platform and remember looking at those manuals in envy!

------
mreome
I found the SFML documentation to be one of the few cases where I didn't find
myself looking for third-party API documentation or tutorials.

------
mariogintili
[http://docs.sunlight.is/#overview](http://docs.sunlight.is/#overview)

------
k0t0n0
Stripe and the worst one has to be Braintree.

------
jackgolding
plot.ly has quite nice documentation in very good detail - ESPECIALLY their
examples using multiple languages

------
steerpike
I still haven't found a single API as quick and easy to get started and test
with than Flickrs

------
sarah123ed
The manual that came with the Coherent (Unix) os by the Mark Williams Co.

------
scarface74
Boto3 - Amazon’s AWS library for Python.

------
foobaw
What are people's thoughts on Swagger?

~~~
steve_adams_86
I feel like people want swagger to generate good docs for them, so they jam
all the auto-gen annotations and what not into their code base and pump out
the default generated docs and more or less leave it at that. And it's awful.
The code base swells up with annotations and the docs are permanently
neglected.

I haven't come across many swagger-based docs that I liked.

Having said that, I agree that it's a problem with the user, not the tool.
Swagger is fine, you should just put some effort into using it well.

------
meesterdude
i've found highcharts documentation to be really exceptional.

------
moltar
Stripe

------
princeb
MATLAB

------
pacuna
AWS CLI APIs in general are very clean and intuitive to follow through their
help menus.

