Description

We recently added endpoint descriptions to the generated OpenAPI specs, which render in the SwaggerUI sandbox. In some cases, the endpoint descriptions are old and confusing for readers. This work focuses on updating missed proposals, and generally raising the bar on the endpoint descriptions.

Conditions of acceptance

• Update Documentation/API documentation with initial set of style guide recommendations
• GET /page/{title}/history
  • Description: Returns information about the latest revisions to a wiki page, in segments of 20 revisions, starting with the latest revision. The response includes API routes for the next oldest, next newest, and latest revision segments, letting you scroll through page history.
• GET /page/{title}/history/counts/{type}
  • Description: Returns basic data about a page's history, such as the number of edits made by different types of users, or how many reverts have occurred on the page. For more information and metrics to understand how readers and editors interact with Wikipedia and other Wikimedia projects, see the Analytics API.
  • Note: Shortened a little for clarity
• POST /transform/wikitext/to/html/
  • Description: Converts any wikitext into HTML.
  • Note: Removed "any" since it may not be 100% true.
• POST /transform/html/to/wikitext/
  • Description: Converts any HTML into wikitext.
  • Note: Removed "any" since it may not be 100% true.
• [declined] GET /search
  • Description: Searches wiki pages for the given search terms, and returns matching pages.
  • This endpoint returns an OpenSeach description document in XML, not a list of search results. Example: https://en.wiktionary.org/w/rest.php/v1/search

Transform endpoints missing unique description messages

From what I can tell, these endpoints are currently using the same endpoint description strings as POST /transform/wikitext/to/html/ and POST /transform/html/to/wikitext/. So in order to change these endpoint descriptions, someone would need to first create new message strings.

• POST /transform/wikitext/to/html/{title}
  • Description: Converts the wikitext of a given page to HTML. The wikitext request body parameter must be provided, but can be left empty to receive the full page. The response body contains the rendered HTML of the page.
• POST /transform/html/to/wikitext/{title}
  • Description: Converts HTML of a given page to wikitext. The html request body parameter must be provided, but can be empty to receive the full page. The response body contains the wikitext of the page.
• POST /transform/wikitext/to/html/{title}/{revision}
  • Description: Converts the wikitext of a given revision to HTML. The wikitext request body parameter must be provided, but can be left empty to receive the full revision. The response body contains the rendered HTML of the revision.
• POST /transform/html/to/wikitext/{title}/{revision}
  • Description: Converts HTML of a given revision to wikitext. The html request body parameter must be provided, but can be empty to receive the full revision. The response body contains the wikitext of the revision.

Related work:
https://phabricator.wikimedia.org/T393467