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.

These standards apply only to APIs used on Wikimedia wikis. For information about APIs that are available with any instance of MediaWiki, see APIs.

As part of the ongoing 2025-2026 Wikimedia Foundation objective to evolve API infrastructure, these standards should be considered unstable and may change without notice.

Quickstart

To set up documentation for a Wikimedia API:

1. Create an OpenAPI description for the API reference docs, and add it to Special:RestSandbox.
2. Create an API landing page on mediawiki.org using this template.
3. Ensure that the OpenAPI description links to the landing page in the top-level externalDocs field.
4. Add the API to the API catalog.

Information architecture

 ├── Wikimedia APIs landing page
 │   ├── Wikimedia APIs/Changelog
 │   ├── Wikimedia API policies (such as Wikimedia APIs/Rate limits)
 │   ├── Wikimedia API guides (such as Wikimedia APIs/Content reuse)
 ├── Individual API landing page (such as Link Recommendation API)
 │   ├── Individual API subpages
 ├── API tutorial
 ├── API sandbox (Special:RESTSandbox)

Wikimedia APIs landing page

The central landing page (Wikimedia APIs) lets you discover all documentation related to Wikimedia APIs. It supports these navigation paths:

• Navigate to an individual API landing page from the API catalog
• Navigate to a tutorial or to a page linked in a use case section
• Navigate to the API sandbox

Subpages of Wikimedia APIs include policies and guides that apply to all (or several) APIs as well as the unified changelog and style guide.

Individual API landing page

An individual API landing page includes (or links to) all the information a user needs to use the API. If an API landing page becomes too long, you can create subpages that align with API documentation #content patterns.

Although landing pages seem to duplicate information found on the Wikimedia APIs landing page and in the lead sections of OpenAPI descriptions, individual API landing pages are useful for discoverability and search optimization.

Tutorials

Tutorials use a flat structure and should not be subpages. This structure keeps tutorial titles short and allows tutorials to use multiple APIs.

Content patterns

This section links to guidance about what to include in each of the sections of API documentation. While the organization of the 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.

Landing page

The landing page provides an entry point for the API's docs with navigation for both new and experienced users, and contact info for maintainers.

Examples:

• Template
• Link Recommendation API

At a minimum, an individual API landing page must include:

• a description of the API's functionality
• the status of the API (such as stable or experimental)
• the type of access available (such as public or restricted)
• which Wikimedia projects the API can access
• the access policy (preferably as a link to Wikimedia APIs/Access policy)
• the stability policy (preferably as a link to Wikimedia APIs/Stability policy)
• the supported authentication methods (if applicable)
• API reference docs (preferably as a link to the API sandbox)
• a quick start example (or a link to a quick start guide)
• how to report bugs
• how to ask questions and get help
• how to contribute
• a link to Wikimedia APIs

Especially for more complex APIs, an individual API landing page may also include, if applicable:

• features of the API
• links to explanations of concepts related to the API
• links to guides related to the API (including any relevant subpages of Wikimedia APIs)
• links to tutorials related to the API

Overview

If a landing page becomes too long, you can move some content to an overview page. An overview page can help users understand what the API offers, basic concepts behind the data, and the usage policies and requirements.

Examples:

• Template
• Analytics API

Tutorial

A tutorial teaches how to accomplish a goal. Learn more.

Examples:

• API:Holidays viewer

Guide

A guide takes users step-by-step through completing specific tasks. Learn more.

Examples:

• Wikimedia APIs/Conditional requests

Concept

A concept page explains the underlying theory behind an aspect of the API.

Examples:

• Page views

Reference

The reference docs describe the full technical details of the API's behavior. Wikimedia APIs should use an OpenAPI description (OAD) to produce interactive reference docs. Wikimedia OADs are served through Special:RestSandbox on all Wikimedia wikis where the API is available.

Get started with OpenAPI

• Learn how to create an OAD in MediaWiki
• Read the Wikimedia OpenAPI style guide
• Explore the Wikimedia OpenAPI example
• [Work in progress] Improve OAD quality using the Wikimedia OpenAPI Spec Linter

Learn more about OpenAPI

• OpenAPI specification v3.0.0
• Live preview for OADs

OADs outside of MediaWiki

To add an OAD outside of MediaWiki to Special:RestSandbox, add the public URL for the OAD to wgRestSandboxSpecs in the Wikimedia config. See this example patch.

Changelog

The changelog provides a record of all notable changes to the API. Wikimedia APIs should use the unified changelog. For APIs outside the scope of the unified changelog, see Documentation/API documentation/Changelog.

See also

• Documentation/Tools#API documentation tools