Documentation/API documentation
API documentation describes the concepts and technical details necessary to use an API. This page defines standard patterns and guidelines for the structure and contents of Wikimedia API documentation.
 | This page is currently a draft.
|
Wikimedia API documentation guidelines
[edit]Each Wikimedia API should follow these patterns to promote consistent structure and presentation of information across APIs.
API documentation structure
[edit]While each API is unique and may have different pieces of information to include, the API's documentation should implement a structure that reflects the major types of documentation. This means, at minimum, each API's documentation contains the following pieces of content organized into a structure similar to the outline below.
├── Landing page ├── Overview content │ ├── API features and status │ ├── Key concepts and resources │ ├── Access policy │ ├── Rate limits │ ├── Stability policy │ ├── Data formats ├── Tutorials and guides │ ├── Quick start tutorial │ ├── Authentication │ ├── (Other tutorials) │ ├── Recipes and guides for common tasks ├── Reference content │ ├── Sandbox │ ├── API reference (if separate from sandbox) │ ├── Status codes (if not included in sandbox) ├── Contact and maintenance content │ ├── Get help │ ├── Report issues │ ├── Contribute │ ├── Changelog
The above outline is a guide that reflects how the most common pieces of API documentation can be placed into logical groupings that support developer workflows. While the organization of your docs may differ slightly, you should try to adhere to these general groupings. For example, don't put explanatory information about an API's data within a tutorial. Instead, link from the tutorial to the conceptual information.
API documentation content patterns
[edit]This section links to guidance about what to include in each of the sections of your API documentation.
Provides an entry point for the API's docs with navigation for both new and experienced users, and contact info for maintainers.
Helps users understand what the API offers, basic concepts behind the data, and the usage policies and requirements.
Guides users step-by-step through completing specific tasks using the API.
Describes the full technical details of the API's behavior.