Documentation/API documentation/Reference

This page provides guidelines on how to document an API using the OpenAPI description (OAD, often referred to as a "spec").

Documenting an API in an OAD happens through the use of different fields in the tree structure of the OAD JSON or YAML file. This guide contains information on what fields to include in the OAD and 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 Documentation/API documentation.

For an example of an OAD that follows this style guide and passes the Wikimedia OpenAPI linter checks, see the OAD example.

This section contains information about fields that are required or recommended in Wikimedia OpenAPI descriptions as defined in the ruleset used by the Wikimedia OpenAPI linter.

In general, to lower the number of linter issues related to the fields missing from your OAD:

• Provide a link to the documentation in the top-level externalDocs field.
• Provide the general information about the API, such as title, version, description, license, contact details, and terms of service, in the info object.
• Whenever possible, fill in the summary and description fields.
• Ensure that every request body and response has a schema.
• Ensure that every parameter, request body, and response has examples.

Required fields:

• externalDocs
• <example object>.value or <example object>.externalValue, but not both
• <info object>.description
• <info object>.license.name
• <info object>.title
• <info object>.version
• <link object>.operationId or <link object>.operationRef, but not both
• <operation object>.description
• <operation object>.operationId
• <operation object>.summary
• <parameter object>.description
• <parameter object>.in
• <request body content>.schema
• <request body object>.description
• <response content>.schema
• <response object>.description
• <schema property>.description
• <schema property>.type
• <server object>.url

When a required field is missing from the OAD, the OpenAPI linter will raise an error.

Recommended fields:

• externalDocs.description
• externalDocs.url
• tags, when operation tags are in use
• <component schema> examples in the appropriate locations
• <example object>.description
• <example object>.summary
• <info object>.contact
• <info object>.contact.name
• <info object>.contact.url
• <info object>.license
• <info object>.license.url
• <info object>.termsOfService
• <link object>.description
• <media type object> examples in the appropriate locations
• <operation object>.tags, when top-level tags exist
• <parameter object> examples in the appropriate locations
• <security scheme object>.description
• <server object variable>.description
• <server object>.description, when more than one server exists

When a recommended field is missing from the OAD, the OpenAPI linter will raise a warning or, for less important fields, an info issue.

Note that if a given field is recommended, and a field under it in the structure is required, that requirement only applies if the higher-level field exists. Likewise, if a field isn't recommended or required, but a field under it in the structure is recommended, that recommendation only applies if the higher-level field exists. For example, the info.license.name field is only required if the recommended parent - info.license - exists.

Additionally, note that this section doesn't mention fields required directly by the OpenAPI specification (for example, openapi, or paths). The Wikimedia OpenAPI linter tool and the linter in CI will still identify issues related to these fields.

This section explains how to write values for different OpenAPI description fields.

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
• This field is required.

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>".

For complete services:

• MediaWiki REST API
• Wikimedia REST API

For subsets of API functionality:

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

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
• This field is required.
• 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 and other relevant information.

Avoid adding too many links to the service description. In general, use the fields intended for that purpose, such as contact, externalDocs, license, and termsOfService. If there's no dedicated field suitable for a link you want to include, you can add it to the documentation (linked in the info.externalDocs field). If the link must be included in the OAD, add it to the service description.

• Media Analytics provides data about requests for media files on Wikimedia projects.
• Device Analytics provides data about the number of unique devices that access Wikimedia projects.
• Edit Analytics provides data about the number of edits and edited pages on Wikimedia projects.

The contact object provides contact information for the API. In Wikimedia API descriptions, this object should contain information about the team maintaining the API, and a link to the team's page. It's also possible to provide an email address.

• OpenAPI field: info.contact
• This field is recommended.

When adding contact information to the OAD:

• Provide a full team name in the info.contact.name field - for example, "MediaWiki Interfaces Team".
• Provide a link to the team page of the team maintaining the API in the info.contact.url field. If the team has multiple pages, link to the one with contact details. Use a localized link if available - for example, "https://www.mediawiki.org/wiki/Special:MyLanguage/MediaWiki_Interfaces_Team".
• Provide an email address in the info.contact.email field if that's the team's preferred way of contact.

The terms of service field provides a link to the terms of service of the API. In Wikimedia API descriptions, this field should always link to wikimedia:Special:MyLanguage/Policy:Terms of Use#12._API_Terms.

• OpenAPI field: info.termsOfService
• This field is recommended.

The license object provides license information for the API. In Wikimedia API descriptions, this object specifies the license of data returned by the API.

• OpenAPI field: info.license
• This field is recommended.

When specifying the license:

• Use a full license name in the name property - for example, "Creative Commons Attribution-Share Alike 4.0".
• Provide the URL of full license text in the url property - for example, "https://creativecommons.org/licenses/by-sa/4.0/".
• Add extra license information to the #Description field (info.description) if it's impossible to fully explain data licensing using a single license object.

Operation summary acts as a title and is commonly used to distinguish operations from one another.

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

When writing a summary:

• Use short verb phrases without articles or periods. If you're not sure what verb is appropriate:
  • Use "Get <item>" for operations that return individual data records (Example: Get item's aliases)
  • Use "Get number of" for operations that return numerical data (Example: Get number of edits)
  • Use "List most-" for operations that return a ranked list (Example: List most-edited pages)
  • Use "Create <item>" for operations that add new data records to the system (Example: Create multiple reading lists for current user)
  • Use "Update <item>" for operations that change data records (Example: Update reading list)
  • Use "Delete <item>" for operations that remove data records (Example: Delete reading list)
  • Follow the same pattern when describing operations 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 operations, so you don't need to include "for a project" in the operation summary
• For operations 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 operation
• Always prefix numerical data points with "number of", such as "Get number of page views"
• Use two words for "page views"

• 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

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

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

When writing an operation 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 operations
  • "Creates", for POST operations
  • "Updates", for PUT and PATCH operations
  • "Deletes", for DELETE operations
• 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

• 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.

Operation identifier is a string that uniquely identifies an operation.

• OpenAPI field: paths.[path].[operation].operationId
• This field is required for every operation in the OpenAPI description.
• This field must have a unique value.

When defining the operationId field, follow common programming naming conventions. One way to create this identifier is to convert the operation summary into a single word in camel case, snake case, or similar - for example, "verifyCustomer", "getPetById".

Note Note: If your API is defined through the MediaWiki REST framework, you can ignore this section, because ModuleSpecHandler.php automatically generates operation identifiers for your routes.

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 operations should have the same description. The best way to achieve this is to either reuse parameter definitions, or to build and use a glossary of request parameters.

When writing a parameter description:

• Use a short noun 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.

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

Response description provides an explanation of the response returned by the API.

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

When writing a response description:

• Use a short 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

• 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 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 operations should have the same description. The best way to achieve this is to either reuse response definitions, or to build and use a glossary of response properties.

When writing a response property description:

• Use a short noun 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.

• 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

Use tags to group operations. You can add tags in the tags property of the OpenAPI object in the OAD. For each tag, specify a name and a description. You can then reference the tag inside the tags property for an operation.

For example:

1. Specify a tag:

   tags:
   -name:Pages
   description:Operations related to pages
   

2. Add the tag under an operation:

   paths:
   /page/updatePage:
   put:
   tags:
   -Pages
   summary:Update page
   operationId:updatePage
   ...
   

This tags the operation with the "Pages" tag, adding it to the "Pages" group. Operations in the same group typically appear together in OpenAPI sandboxes and tools.

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. Use this field to link to the documentation landing page for 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 operations 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).

In addition to the dedicated externalDocs fields, you can link to external documentation from description fields using CommonMark link syntax. Keep in mind that adding too many links can be distracting and unhelpful. You can minimize the negative impact of links in descriptions by following these recommendations:

• Consider whether a link provides valuable information to API users and is necessary to understand how the API works. If not, skip it.
• Try to only add links to the high level #Description field (info.description). This field should already contain a broad range of information, so new links added in an organized way shouldn't negatively impact the reading experience.
• Avoid adding more than one external link to a description (except in the info.description field).

The OpenAPI description has dedicated fields for resources such as license and terms of service. For more information on these fields, see #License and #Terms_of_service. If these fields are insufficient to document the complexities of data licensing or terms of service, add the extra information to the #Description field (info.description).

When describing Boolean properties, use any of the following phrasings:

• "Whether <property meaning when its value is true>" - for example, "Whether the page is a redirect"
• "Indicates whether <property meaning when its value is true>" - for example, "Indicates whether the page is a redirect"
• "<property meaning when its value is true>" - for example, "Page is a redirect"
• "`true` if <property meaning when its value is true>" - for example, "`true` if the page is a redirect"

It's best to apply the same phrasing consistently throughout the OAD, but using different phrasings is acceptable and can improve clarity and correctness. For example, you might want to differentiate between Boolean properties in request parameters and response properties.

When using the enum field to describe a property, document meanings of all permitted values in the property description. For example:

description:|-
Filter to use for listing orders:
* `customer` - List orders made by a customer
* `date` - List orders created between two dates
schema:
type:string
enum:
-customer
-date

The format field in the schema object provides information about the format of a given object, item, or property. It serves as extra documentation and might affect code generated from the OpenAPI description. When setting this field, keep in mind that some values have reserved meaning as documented in the OpenAPI Formats Registry. Verify that your usage of these values matches their meaning in the registry to ensure correctness of code generated from the description. For any format not covered in the registry, use a custom, descriptive value.

• OpenAPI field: *.schema.**.format

Guidelines available on this page are a part of a suite of resources and tools used to maintain OpenAPI descriptions for Wikimedia APIs. The other resources are:

• Wikimedia Spectral ruleset, used by:
  • Wikimedia OpenAPI linter deployed as a tool on Toolforge
  • Linter deployment in CI (work in progress per T422920)
• Linter rule reference, available in the ruleset repository, in RULE_REFERENCE.md
• OAD example, available in the ruleset repository under tests/oad_example

When changing this style guide, keep in mind the impact that your changes might have on the other resources. If in doubt, reach out to:

• The MediaWiki Interfaces Team, if you have questions about the ruleset, the OAD example, the linter tool, or the linter deployment in CI.
• The Technical Documentation Team, if you have questions about the ruleset, the OAD example, or this style guide.
• The Test Platform Team, if you have questions about the linter deployment in CI.

• OpenAPI