Ask HN: Best Documented Web APIs and Integrations?
8 comments
Stripe, Parse, Twilio, SendBird.
This is a good overview of the different things that make up great docs: https://zapier.com/engineering/great-documentation-examples/
I think a great developer docs experience is a really tough thing to do well. You need to have great design, great writing, and great tech. The existing docs platforms out there (like Readme.io) all suck (especially for anything beyond REST API docs), so you really need to roll your own.
I've done some consulting in this area for clients who wanted amazing docs experiences, so ping me if you want some more ideas / feedback.
This is a good overview of the different things that make up great docs: https://zapier.com/engineering/great-documentation-examples/
I think a great developer docs experience is a really tough thing to do well. You need to have great design, great writing, and great tech. The existing docs platforms out there (like Readme.io) all suck (especially for anything beyond REST API docs), so you really need to roll your own.
I've done some consulting in this area for clients who wanted amazing docs experiences, so ping me if you want some more ideas / feedback.
Airtable has a pretty awesome api documentation.
Basically, when you create a table and see its api documentation, it is generated on the fly to show you the rest endpoints specific to that table only.
Pretty awesome actually, worth checking it out.
Stripe has good api docs too.
Basically, when you create a table and see its api documentation, it is generated on the fly to show you the rest endpoints specific to that table only.
Pretty awesome actually, worth checking it out.
Stripe has good api docs too.
https://docs.particle.io/reference/api/
Amazing IoT startup and amazing documentation
Amazing IoT startup and amazing documentation
Follow up question: Is there a framework for creating and maintaining these API docs, or is it hand-coded?
Maxime from Algolia here.
There is a lot of things out there to build docs.
(Sphinx, readme.io, jekyll, middleman, web frameworks, ...).
All those tools are good at what they do. When you want to do something very specific/custom, you will always end up needing something outside the scope of those products.
So far at Algolia, middleman is the one we're using for our main documentation. We had to tweak it a lot and reimplement some parts but it works and we should be able to keep it running for a while.
All those tools are good at what they do. When you want to do something very specific/custom, you will always end up needing something outside the scope of those products.
So far at Algolia, middleman is the one we're using for our main documentation. We had to tweak it a lot and reimplement some parts but it works and we should be able to keep it running for a while.
https://apiblueprint.org/tools.html and https://swagger.io/ are open documentation standards for APIs with editors, renderers and tools to mock a test environment.
For my own API (https://geocoder.opencagedata.com/api) it's hand-coded because the output of the tools are too complex when you have only 1-2 methods.
For my own API (https://geocoder.opencagedata.com/api) it's hand-coded because the output of the tools are too complex when you have only 1-2 methods.
Which are the best API documentations you know? Comprehensiveness, Readability, Usability/UX, Look&Feel, extensive use of standards... whatever factor makes it special/favourable.
Looking for role models.