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