Documentation/API documentation/Reference

Tracked in Phabricator
Task T405571

This page provides guidelines on how to document an API using the OpenAPI description file (OAD). Documenting the API within OAD happens through the use of fields such as title, summary, and description, as well as supplementary fields like externalDocs. This guide contains instructions on how to write values for these fields that are correct and consistent.

For general information about using OAD files to document and provide examples for your API, see https://learn.openapis.org/specification/docs.html. For general information about documenting APIs within the Wikimedia ecosystem, see https://www.mediawiki.org/wiki/Documentation/API_documentation.

OpenAPI description fields

Title

Service title is the high-level name of the service described by the specification. This can be either the entire API or a sub-set of its functionality.

• OpenAPI field: info.title

The value of this field is typically determined by the name of the API. If the OAD describes a sub-set of API functionality, the title uses the following template: "Wikimedia <data available in the API> <API or sub-set name or description>".

Examples

For complete services:

• MediaWiki REST API
• Wikimedia REST API

For subsets of API functionality:

• Wikimedia Device Analytics
• Wikimedia Edit Analytics
• Wikimedia Media Analytics

Description

Service description is the high-level explanation of the purpose of the service (either an API or a sub-set of API functionality) documented in the OAD.

• OpenAPI field: info.description
• Allows CommonMark - CommonMark is a variant of Markdown. It differs from other variants, most notably GitHub Flavored Markdown. Not all syntax supported by other variants is valid CommonMark.

When writing a service description, start with the name of the service and proceed to describe the type of data it provides, license, and other relevant information.

Examples

• Media Analytics provides data about requests for media files on Wikimedia projects.\nData provided by this API is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/).
• Device Analytics provides data about the number of unique devices that access Wikimedia projects.\nData provided by this API is available under the [CC0 1.0 license](<nowiki>https://creativecommons.org/publicdomain/zero/1.0/).
• Edit Analytics provides data about the number of edits and edited pages on Wikimedia projects.\nData provided by this API is available under the [CC0 1.0 license](<nowiki>https://creativecommons.org/publicdomain/zero/1.0/).

Paths

Summary

Endpoint summary acts as a title and is commonly used to distinguish endpoints from one another.

• OpenAPI field: paths.[path].[operation].summary

When writing a summary:

• Use short verb phrases without articles or periods
• Use "Get <item>" for endpoints that return individual data records (Example: Get item's aliases)
• Use "Get number of" for endpoints that return numerical data (Example: Get number of edits)
• Use "List most-" for endpoints that return a ranked list (Example: List most-edited pages)
• Use "Create <item>" for endpoints that add new data records to the system (Example: Create multiple reading lists for current user)
• Use "Update <item>" for endpoints that change data records (Example: Update reading list)
• Use "Delete <item>" for endpoints that remove data records (Example: Delete reading list)
• Follow the same pattern when describing endpoints with functionality that can't be explained in these simple terms (Example: Opt user in to reading list functionality)
• If the service provides access to data from multiple projects, treat per-project as the default scope for endpoints, so you don't need to include "for a project" in the endpoint summary
• For endpoints that support a more granular scope than per-project, such as per-file or per-page, use "for a" since it's more clear. (Example: Get number of page views for a page)
• Use "by" to indicate an organizing principle for response data, such as "Get number of page views by country"
• Use "most-" to indicate top or ranked data points, such as "most-viewed pages"
• Use "(legacy)" after the summary to indicate a legacy endpoint
• Always prefix numerical data points with "number of", such as "Get number of page views"
• Use two words for "page views"

Examples

• Get absolute change for a page, in bytes
• Get number of editors
• Get number of edits to a page
• Get number of new pages
• List most-edited pages by number of bytes changed
• List most-requested files
• List most-viewed pages
• List most-viewed pages for a country

Description

Endpoint description acts as the main explanation of the purpose of the endpoint. It describes its use case and provides other helpful information.

• OpenAPI field: paths.[path].[operation].description
• Allows CommonMark syntax

When writing an endpoint description:

• Write in full sentences, starting with a capital letter and ending with a period
• Start the first sentence with a verb, typically:
  • "Returns" or "Lists", for GET endpoints
  • "Creates", for POST endpoints
  • "Updates", for PUT and PATCH endpoints
  • "Deletes", for DELETE endpoints
• Don't duplicate information about the response that's better suited for the response documentation
• Use consistent phrasing, such as "Returns information about" for descriptive resources and "Returns data about" for numeric resources
• Use "page" instead of "wiki page" for conciseness and to avoid longer compound nouns

Examples

• Lists the 100 most-edited pages on a Wikimedia project, ordered by the absolute change in bytes. For example, if a page has an edit that adds 5 bytes and an edit that removes 10 bytes, the absolute change is 15 bytes.
• Returns a time series of numbers of bytes changed on a Wikimedia project, calculated as the net change in page length, in bytes. For example, if an edit adds 5 bytes and an edit that removes 10 bytes, the net change is -5 bytes.
• Returns a time series of numbers of edited pages on a Wikimedia project.
• Lists the 100 most-active editors on a Wikimedia project, ordered by the absolute change in page length introduced by their edits, in bytes. For example, if an editor adds 5 bytes and removes 10 bytes, the absolute change is 15 bytes.
• Returns the approximate number of editors of a Wikimedia project, split by country of origin.
• Returns a time series of numbers of requests for a media file on upload.wikimedia.org.
• Lists the 1000 most-viewed pages on a Wikimedia project.

Request parameter description

Request parameter description provides an explanation of a given parameter, and optionally its purpose and constraints.

• OpenAPI field: paths.[path].[operation].parameters.[parameter index].description
• Allows CommonMark syntax

Important: Parameters with the same name and function across endpoints should have the same description. The best way to achieve this is to build and use a glossary of request parameters.

When writing a parameter description:

• Use a short verb phrase without articles or periods if the parameter requires no additional explanation
• If additional explanation is necessary, use full sentences beginning with a capital letter and ending with a period
• Use CommonMark syntax to format more complex descriptions

Many parameters are already documented. You can re-use their descriptions and examples, or use them as a starting point to write your own.

Examples

• Method of access
• Editor activity range
• Type of user agent
• Page description in URL-encoded format

Response status description

Response description provides an explanation of the status code returned by the API.

• OpenAPI field: paths.[path].[operation].responses.[response].description
• Allows CommonMark syntax

When writing a response description:

• Use a short verb phrase without articles or periods if the response requires no additional explanation
• If additional explanation is necessary, use full sentences beginning with a capital letter and ending with a period

Examples

• Title normalization redirect
• Missing token when using cookie-based authentication. Add a CSRF token to the request body, or use an OAuth authorization flow.
• Invalid limit requested. Set limit parameter to between 1 and 100.

Response property description

Response property description provides an explanation of fields and values returned in the API response.

• OpenAPI field: paths.[path].[operation].responses.[response].schema.properties.[property].description
• Allows CommonMark syntax

Important: Response properties with the same name and function across endpoints should have the same description. The best way to achieve this is to build and use a glossary of response properties.

When writing a response property description:

• Use a short verb phrase without articles or periods if the response property requires no additional explanation
• If additional explanation is necessary, use full sentences beginning with a capital letter and ending with a period
• Use CommonMark syntax to format more complex descriptions

Many properties are already documented. You can re-use their descriptions and examples, or use them as a starting point to write your own.

Examples

• Number of bytes changed
• Number of page views
• Number of unique devices
• Number of edited pages
• Number of editors
• Approximate number of editors
• Number of edits
• Top-level response array
• Net change in bytes

Grouping endpoints

Use tags to group endpoints. You can add tags under the tags path of the OAD. For each tag, specify a name and a description. You can then reference the tag inside the tags field for an operation.

For example:

1. In tags, specify a tag with
   • name: Page content
   • description: Page content in different formats
2. Under a given GET operation for a path, add tags: ["Page content"]

This tags an operation under the endpoint with the "Page content" tag, adding it to the "Page content" group. Operations in the same group typically appear together in OpenAPI sandboxes and tools.

Linking to external documentation

OpenAPI description supports links to external documentation. You can add these links at different levels of the description:

• at the top level, in externalDocs - for external documentation describing the API
• at operation level, in paths.[path].[operation].externalDocs - for documentation describing an operation
• at tag level, in tags.[tag number].externalDocs - for documentation describing a tag or a group of endpoints tagged with the given tag
• at schema object level, in schema.externalDocs - for external documentation of the schema

The externalDocs object must contain a URL and can optionally contain a description. For details, see the OpenAPI specification (https://spec.openapis.org/oas/v3.0.0.html#external-documentation-object).