Several Wikimedia API endpoints use a page title as a path parameter. The purpose of this task is to decide on an accurate description for title parameters and update the docs for any applicable APIs.

Problem statement

It would be ideal to be able to document the title parameter as simply "Page title". However, this may lead to confusion if an API users tries to use a title in the wrong format. For example:

• Some special characters don't work unless encoded:
  • example page title: Fate/stay_night
  • example API URL with 404 response due to / in page title: https://en.wikipedia.org/w/rest.php/v1/page/Fate/stay_night
• Titles with spaces don't work with curl:
  • example: curl "https://en.wikipedia.org/w/rest.php/v1/page/North America"

Consideration 1: Correct format

It seems that the most correct format for titles in API path parameters is one in which, first, spaces are replaced with underscores, and then the result is URL-encoded. Example: Man%27s_best_friend (https://en.wikipedia.org/w/rest.php/v1/page/Man%27s_best_friend) This is the format returned by the MediaWiki REST API when providing an API URL (see html_url in this response).

Consideration 2: API sandbox behavior

However, the format described above does not work in the API sandbox since swagger UI automatically encodes path parameters:

• Putting Man%27s_best_friend into the sandbox, results in a request for Man%2527s_best_friend, which 404s
• Putting Man's best friend into the sandbox, results in a request for Man%27s%20best%20friend, which results in a redirect when using curl

Since the documentation will be read primarily in the context of the sandbox, we should call this out.

Proposed description

"Page title. To format the title, replace spaces with underscores, and then URL-encode the result (example: Steller%27s_jay). In the API sandbox, replace spaces with underscores, but do not URL-encode (example: Steller's_jay)."

Note: I had originally hoped to use "API explorer" instead of "API sandbox", but I found the term "sandbox" has already been well established in the context of Special:RESTSandbox, and that it would be more confusing to try and introduce a different term at this point.

Potential future opportunities for improvement

(Out of scope for this task)

• API responses could consistently contain page titles in a format suitable for use with the API. For example, the MediaWiki REST API Search pages endpoint returns page titles only in key (Fate/stay_night) and title (Fate/stay night) formats.
• The API could accept any format for page titles
• The API could accept page IDs instead of titles
• The API sandbox could behave the same way as the API