Data Platform/Systems/AQS/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 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.
Field 	Value
basePath 	/api/rest_v1/metrics/
host 	wikimedia.org
schemes 	https
termsOfService	https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Terms_of_Use
version 	1
== 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.
Term 	Preferred description 	Preferred example 	Comment
access 	Method of access 	all-access 	Also a response property
access-site 	Method of access 	all-sites 	Also a response property
activity-level 	Editor activity range 	all-activity-levels 	Also a response property
agent 	Type of user agent 	all-agents 	Also a response property
article 	Page description in URL-encoded format. The API sandbox encodes titles automatically 	Jupiter 	
country / countries	Country code in ISO 3166-1 alpha-2 format 	FR 	Also a response property
day 	Day in DD format, or `all-days` 	"02" 	Also a response property
editor-type 	Type of editor. `group-bot` for registered accounts belonging to the bot group; `name-bot` for registered accounts with bot-like names 	all-editor-types 	Also a response property
end 	
* Last day to include in YYYYMMDD format
* Last day and hour to include YYYYMMDDHH format 	20230126 (depending on format) 	
file-path 	Path to the file on upload.wikimedia.org in URL-encoded format. The API sandbox encodes paths automatically 	/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg	Also a response property. As a response property, this value is not URL-encoded.
granularity 	Time interval between data points 	monthly 	Also a response property
media-type 	Type of media file 	all-media-types 	Also a response property
month 	Month in MM format 	"01" 	Also a response property
page-title 	Page title in URL-encoded format. The API sandbox encodes titles automatically 	Jupiter 	Also a response property. As a response property, this value is not URL-encoded.
page-type 	Type of page 	all-page-types 	Also a response property
project 	Domain and subdomain of a Wikimedia project. For all projects, use `all-projects`. For data grouped by project family, use `all-[family]-projects`; for example, `all-wikipedia-projects`	en.wikipedia.org 	Also a response property. Not all endpoints support the `all-family-projects` option.
referer 	Origin of the request. Can be a domain of a Wikimedia project, or any of the allowed values: `all-referers`, `internal`, `external`, `search-engine`, `unknown`, or `none` 	all-referers 	Also a response property. Shouldn't start with "The", no period at the end.
start 	
* First day to include in YYYYMMDD format
* First day and hour to include in YYYYMMDDHH format 	20230102 (depending on format) 	
year 	Year in YYYY format 	2023 	Also a response property
== 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.
Term 	Preferred description 	Preferred example 	Comment
abs_bytes_diff 	Number of bytes changed 	1505 	
count 	Number of page views 	42 	Only used in the legacy pageviews endpoint
devices 	Number of unique devices 	74 	
edited_pages 	Number of edited pages 	16 	
editors 	Number of editors 	68 	
editors-ceil 	Approximate number of editors 	300 	
edits 	Number of edits 	25 	
items 	Top-level response array 	N/A 	
net_bytes_diff 	Net change in bytes. A negative value indicates bytes removed 	34 	
new_pages 	Number of new pages 	17 	
new_registered_users	Number of newly registered users 	93 	
offset 	Number of devices with one visit or an unknown number of visits	49 	
rank 	<response record> rank
For example:
* Page rank
* Editor rank 	1 	
requests 	Number of requests 	55 	
timestamp 	Timestamp in <format> format 	20230101 (depending on format)	
underestimate 	Number of devices with two or more visits 	80 	
user_text 	Wikimedia username, or `null` for anonymous users 	null 	
views 	Number of page views 	65 	
views_ceil 	Approximate number of page views 	2000