AQS 2.0/OpenAPI spec style guide

The purpose of this guide is to help you write an OpenAPI specification for services and endpoints in a way that's consistent with existing specs.

The first sections of this page describe the language style you should use when documenting high-level elements of the specification - service and endpoint titles and descriptions.

The later sections talk about how to document parameters and properties.

Service title

Service title is the high-level name of the service described by the specification. You set it in the main.go file in your project, in the @title field.

Service title typically uses the following template: "Wikimedia <data described by the service> Analytics".

Examples of current service titles:

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

Service description

Service description is the high-level explanation of the purpose of the service documented by the specification. You set it in the main.go file in your project, in the @description field.

Examples of current service descriptions:

• 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](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](https://creativecommons.org/publicdomain/zero/1.0/).

Note that these examples use Markdown syntax to specify links (as you would in your Go source files). To introduce a new line in the description, instead of \n add another @description field like in this file.

Service - other fields

The OpenAPI specification of a service can contain other fields. This section provides a list of values for other fields typically present in the OpenAPI specification of AQS services. You set them in main.go. These values shouldn't change very often so you can copy them directly to your spec.

Endpoint summary

Endpoint summary acts as a title of the endpoint, displayed by the sandbox component on the documentation website. Specify it in the *_handler.go file of a given endpoint, in the @summary field.

When writing a summary:

• Use short verb phrases without articles or periods
• 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)
• 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 "(legacy)" after the summary to indicate a legacy endpoint
• Use "most-" to indicate top or ranked data points, such as "most-viewed pages"
• Always prefix numerical data points with "number of", such as "Get number of page views"
• Use two words for "page views"
• To differentiate net and absolute difference:
  • Use "bytes changed" or "absolute change" when talking about absolute difference. Be sure to clarify in the endpoint description how this value is calculated and that it can only be positive.
  • Use "net difference in bytes" or "net change" when talking about net difference. Be sure to clarify in the endpoint description how this value is calculated and that it may be negative.

Examples of current endpoint names:

• 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

Endpoint description

Endpoint description serves as an explanation of the purpose of an endpoint and is displayed inside the sandbox component on the documentation website.

The description always starts with a verb (typically "Returns" or "Lists") and uses full sentences ending with periods.

Examples of endpoint descriptions currently in use:

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

Endpoint - request parameters

Request parameters are the fields and values you provide as input to the API when requesting data. You specify them in the @param lines in the *_handler.go file of a given endpoint. Note that descriptions of parameters are displayed in the sandbox component on the documentation website.

When describing a parameter, be sure to use a short phrase without periods and with minimal use of articles. For type parameters (except for project), use the all- version as an example.

Many parameters are already documented in existing specifications. You can re-use their descriptions and examples, or use them as a starting point to write your own. The following examples use Markdown syntax in descriptions (as you would in your Go source files). Notice the use of code snippets (Example: `all-days`) to indicate possible values.

Response properties

Response properties are the fields and values returned in the API response. You specify them in Go files in the entities directory. Note that descriptions of response properties are displayed in the sandbox component on the documentation website.

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