Ask HN: What is the best API documentation you have ever seen? | Hacker News Reader

Ask HN: What is the best API documentation you have ever seen?

67 pointsenjayz61 comments

Stripe API docs. There have probably been many past threads about this.

I'm very impressed by those docs. Anyone has insights how they were made?

Looks like they were partly generated, otherwise it would be impossible to keep everything consistent - especially with the many language examples. They also seem to generate an OpenApi Spec (or use this as a basis for generating the docs?): https://github.com/stripe/openapi

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.

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.

There have probably been many past threads about this.

There have been. The following is a good search to use to find other discussions.

https://hn.algolia.com/?query=&sort=byPopularity&prefix&page...

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

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.

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

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.

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.

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.

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.

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

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.

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

I really like the Lua reference manual. All on a single page (e.g. 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.

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.

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

The SQLite docs were frequently better than blog posts or SO questions about my issues, which was a first for me.

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/

Oh, that poster is nice!

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

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

I believe these are called "railroad diagrams". BNF is text only as far as I know.

There are BNF to railroad diagram generators (they take a "grammar file", often BNF, and output a railroad diagram).

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... [2] https://www.haskell.org/haddock/

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

Qt docs, python docs, cppreference, code synthesis odb

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.

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

I feel similarly about Python. I never really had to interact with it beyond using it as a calculator on the command line until a project I was a part of earlier in the year had a utility Python script introduced and I needed to hack on it to make desired changes. Then, more recently, I started using BeautifulSoup[0] for personal scraping. Of course it feels more trivial now (and now I wish I documented my frustrations so I could be more specific and perhaps help out other Python learners in the future), but it does take a while to adjust to Pythonic code where everyone is using cultural conventions like _foo and __foo and you wonder what the hell __foo__ is[1].

More on-topic, searching is a major weakness of Python's docs. What's that? Python just got multi-line strings allowing embedded expressions? They're called f-strings? Let me go read about them[2]. I can't link it, but even using Startpage the immediate results are a post from RealPython and PEP498 and while both are great, they aren't terse enough to be frequently referenced. If you search for "formatted string literal"[3] in the docs it takes 10 results before you reach something explicitly talking about them. And then you need to follow the links a couple times to reach https://docs.python.org/3/reference/lexical_analysis.html#f-... (notice it is anchored as "f-strings" which was the first term we searched for).

While the Python docs, when I've found them, have been adequate for me so far -- although I still check up on how others do the things I want to do -- I'm partial to docs such as MDN that cover parameters and return value in one take for reference with more in-depth information as you scroll down, if needed[4].

[0]: https://www.crummy.com/software/BeautifulSoup/

[1]: Here's a start for reading. https://stackoverflow.com/questions/8689964/why-do-some-func...

[2]: https://docs.python.org/3/search.html?q=f-string

[3]: https://docs.python.org/3/search.html?q=formatted+string+lit...

[4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

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.

You can always pick a few projects on GitHub that have a less than ideal readme or set of docs and submit a bunch of PRs at once, I've done that before as a quick way to make myself feel like I'm contributing to the community whenever I don't have the motivation to push through on my own projects.

Thanks so much!! It's a great way for me to help the projects I care about but don't have the skills to contribute .c .h files to haha

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

Happy to take a look and possibly help with the documentation you need :)

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!

Happy to pay! Email me at david@tryretool.com please. :)

(Your profile email isn’t public!)

The requests package for python is nicely documented: http://docs.python-requests.org/en/master/

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.

Not API, but Spark Java (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

Common Lisp HyperSpec - http://www.lispworks.com/documentation/HyperSpec/Front/index...

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

It also has the best motto on the internet: The very definition of class.

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.

I really like the Requests quickstart docs: http://docs.python-requests.org/en/master/user/quickstart/

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

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!

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.

http://docs.sunlight.is/#overview

Stripe and the worst one has to be Braintree.

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

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

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

Boto3 - Amazon’s AWS library for Python.

What are people's thoughts on Swagger?

I used to connect to REST (and SOAP/Graphql I guess, but that's not relevant) APIs for a living. Probably connected to about 200 or so. Swagger styled docs are only as good as the devs who write them. They have the potential to be pretty...but I couldn't care less about that.

Some of the worst docs I've ever seen used swagger. Some of the best I've seen used swagger, so the tool doesn't make the docs IMO.

I'd rather you email me a .txt file that's well organized and complete (including a damned baseURL, you heathens) than pretty swagger docs without substance.

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.

OpenApi 3.0 is quite nice to work with. Its verbose to write by hand, though and you also need to know JSONSchema. With the Swagger UI we've had some mixed experiences. Not everything you can express in the Spec is displayed very well. But for developers, it's a nice playground / entrypoint for backend projects. We wouldn't want to miss that. (You also get this for GraphQL with the GraphQL Playground)

One of the most important features of an API Doc is that it tells the complete truth and is always up to date. An OpenApi Spec therefore really "wants" to be auto-generated. There we've had mixed experiences, aswell. If the generator is not working as expected or missing a feature important to you, you're either limited or you take on generating it yourself.

I've used an approach a while ago, I was quite happy with, but it took some effort: Everything API related has one definitite source of truth. Out of that, generate the docs, example and specs you need. Also use this for validation. For Documentation, I've used a wiki. The generated docs or code snippets were generated as Templates, and could be embedded/transcluded in the documentation, which was otherwise hand-written. This provided a nice mix of written and generated content with full flexibility.

With https://github.com/timothycrosley/hug these docs are autogenerated, which is nice.

i've found highcharts documentation to be really exceptional.

Stripe

MATLAB

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

Reply on news.ycombinator.com