How to Write API Documentation: Best Practices and Examples

Watch this video for an introduction to the API technology

What Developers Hate in API Documentation

Adopt spec-driven development

API Console lets you build a web portal for your API docs from RAML and OpenAPI specifications
Pawel Psztyc

Write for the entry level

  • developers who will intimately interact with the docs
  • decision-makers like CTOs and solution architects who want to determine whether your API will be a good fit quickly
  • observers like journalists, tech writers, and even competitors who won’t necessarily use your API ever.
Amazon Alexa API docs start with explaining what Alexa does and what benefit it can bring to the client
Facebook provides a clear reference for beginners and follows the getting started process step by step

Incorporate must-have sections

SmartBear surveyed 3,000 API practitioners

Use industry-standard layout

HubSpot API docs use a three-column layout
This example from Facebook’s Graph API docs also shows how you can use different tabs to choose between SDKs

Don’t abandon your docs

Great API documentation examples

Medium API documentation

Mailchimp API documentation

  • what an endpoint does and what the guide will let users do
  • what you’ll need — any accesses or accounts a user must get first
  • what each function is with a text description, a code example in several languages, and sometimes screenshots of the interface.

Twilio API documentation

Spotify API documentation

Treat docs with care



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
AltexSoft Inc

AltexSoft Inc


Being a Technology & Solution Consulting company, AltexSoft co-builds technology products to help companies accelerate growth.