API Documentation

Whether writing API documentation for a Web API or a Platform API, good API documentation will usually contain two key major components:

  • Overview
  • Reference

Overview

The overview section is best used to explain why or how an API should be used. This is section for providing developers with information allowing them to quickly read steps to getting started, key concepts, and other sample tutorials and use cases.

The following sections may be found in an Overview section:

  • Abstract
  • Requirements
  • Getting Started
  • Key Concepts
  • Workflow
  • Architecture (Platform APIs)
  • Authentication (Web APIs)
  • Tutorials
  • Sample Code

Reference

The reference section is best used to provide detailed information about the API. This is the section for providing developers with detailed information about the API.

The following should be extensively documented in the API documentation:

  • Classes (Platform APIs)
  • Endpoints (Web APIs)
  • Status Codes (Web APIs)